ETO Development Tools 4

home *** CD-ROM | disk | FTP | other *** search

/ ETO Development Tools 4 / ETO Development Tools 4.iso / Essentials / MPW 411 / CIncludesHelp < prev next >

Wrap

Text File | 1991-04-08 | 3.0 MB | 104,687 lines | [TEXT/MPS ]

Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents. æKY CopyrightNotice æC Copyright Apple Computer, Inc. 1985-1991, All rights reserved. 411 - CIncludes Help - MPW 3.2 Final Release. Friday, April 5, 1991 1:22:42 PM æKY Help CIncludesHelp æKL AboutCIncludesHelp ADSP.h AIFF.h Aliases.h AppleEvents.h Appletalk.h Balloons.h CommResources.h Connections.h ConnectionTools.h Controls.h CRMSerialDevices.h CTBUtilities.h CursorCtl.h DatabaseAccess.h Desk.h Deskbus.h Devices.h Dialogs.h DisAsmLookup.h DiskInit.h Disks.h Editions.h ENET.h EPPC.h ErrMgr.h Errors.h Events.h Files.h FileTransfers.h FileTransferTools.h Finder.h FixMath.h Folders.h Fonts.h Globals.h GestaltEqu.h Graf3D.h HyperXCmd.h Icons.h Language.h Lists.h Math.h Memory.h Menus.h Notification.h OSEvents.h OSUtils.h Packages.h Palettes.h Perf.h Picker.h PictUtil.h Power.h PPCToolBox.h Printing.h Processes.h QDOffscreen.h Quickdraw.h Resources.h Retrace.h ROMDefs.h SANE.h Scrap.h Script.h SCSI.h Segload.h Serial.h ShutDown.h Slots.h Sound.h SoundInput.h StandardFile.h Start.h Strings.h SysEqu.h Terminals.h TerminalTools.h TextEdit.h Timer.h ToolUtils.h Traps.h Types.h Video.h Windows.h StdCLib Assert.h Ctype.h Errno.h FCntl.h Float.h IOCtl.h Limits.h Locale.h Math.h SetJmp.h Signal.h StdArg.h StdDef.h StdIO.h StdLib.h String.h Time.h æKY AboutCincludesHelp æC __________________________________________________________________ Version 1.0 Final -- MPW 3.2 Final Contains Nets & Comm Interface information and bug fixes. __________________________________________________________________ Version 1.0 Beta 6 -- ETO #3 Contains updated InsideMachintosh Volume VI information. __________________________________________________________________ Version 1.0 Beta -- ETO#2 This version contains the InsideMacintosh Volume VI information. æKY ADSP.h æKL attnBufSize dspAttention dspCLDeny dspCLInit dspCLListen dspClose dspCLRemove dspInit dspNewCID dspOpen dspOptions DSPParamBlock DSPPBPtr dspRead dspRemove dspReset dspStatus dspWrite eAttention eClosed eFwdReset errAborted errAttention errDSPQueueSize errFwdReset errOpenDenied errOpening errRefNum errState eTearDown minDSPQueueSize ocAccept ocEstablish ocPassive ocRequest sClosed sClosing sListening sOpen sOpening sPassive TPCCB TRattnParams TRCCB TRcloseParams TRinitParams TRioParams TRnewcidParams TRopenParams TRoptionParams TRstatusParams æKY errRefNum æFc ADSP.h æT #define æD #define errRefNum -1280 /* bad connection refNum */ æC æKY errAborted æFc ADSP.h æT #define æD #define errAborted -1279 /* control call was aborted */ æC æKY errState æFc ADSP.h æT #define æD #define errState -1278 /* bad connection state for this operation */ æC æKY errOpening æFc ADSP.h æT #define æD #define errOpening -1277 /* open connection request failed */ æC æKY errAttention æFc ADSP.h æT #define æD #define errAttention -1276 /* attention message too long */ æC æKY errFwdReset æFc ADSP.h æT #define æD #define errFwdReset -1275 /* read terminated by forward reset */ æC æKY errDSPQueueSize æFc ADSP.h æT #define æD #define errDSPQueueSize -1274 /* DSP Read/Write Queue Too small */ æC æKY errOpenDenied æFc ADSP.h æT #define æD #define errOpenDenied -1273 /* open connection request was denied */ æC æKY dspInit æFc ADSP.h æT #define æD #define dspInit 255 /* create a new connection end */ æC æKY dspRemove æFc ADSP.h æT #define æD #define dspRemove 254 /* remove a connection end */ æC æKY dspOpen æFc ADSP.h æT #define æD #define dspOpen 253 /* open a connection */ æC æKY dspClose æFc ADSP.h æT #define æD #define dspClose 252 /* close a connection */ æC æKY dspCLInit æFc ADSP.h æT #define æD #define dspCLInit 251 /* create a connection listener */ æC æKY dspCLRemove æFc ADSP.h æT #define æD #define dspCLRemove 250 /* remove a connection listener */ æC æKY dspCLListen æFc ADSP.h æT #define æD #define dspCLListen 249 /* post a listener request */ æC æKY dspCLDeny æFc ADSP.h æT #define æD #define dspCLDeny 248 /* deny an open connection request */ æC æKY dspStatus æFc ADSP.h æT #define æD #define dspStatus 247 /* get status of connection end */ æC æKY dspRead æFc ADSP.h æT #define æD #define dspRead 246 /* read data from the connection */ æC æKY dspWrite æFc ADSP.h æT #define æD #define dspWrite 245 /* write data on the connection */ æC æKY dspAttention æFc ADSP.h æT #define æD #define dspAttention 244 /* send an attention message */ æC æKY dspOptions æFc ADSP.h æT #define æD #define dspOptions 243 /* set connection end options */ æC æKY dspReset æFc ADSP.h æT #define æD #define dspReset 242 /* forward reset the connection */ æC æKY dspNewCID æFc ADSP.h æT #define æD #define dspNewCID 241 /* generate a cid for a connection end */ æC æKY ocRequest æFc ADSP.h æT #define æD #define ocRequest 1 /* request a connection with remote */ æC æKY ocPassive æFc ADSP.h æT #define æD #define ocPassive 2 /* wait for a connection request from remote */ æC æKY ocAccept æFc ADSP.h æT #define æD #define ocAccept 3 /* accept request as delivered by listener */ æC æKY ocEstablish æFc ADSP.h æT #define æD #define ocEstablish 4 /* consider connection to be open */ æC æKY sListening æFc ADSP.h æT #define æD #define sListening 1 /* for connection listeners */ æC æKY sPassive æFc ADSP.h æT #define æD #define sPassive 2 /* waiting for a connection request from remote */ æC æKY sOpening æFc ADSP.h æT #define æD #define sOpening 3 /* requesting a connection with remote */ æC æKY sOpen æFc ADSP.h æT #define æD #define sOpen 4 /* connection is open */ æC æKY sClosing æFc ADSP.h æT #define æD #define sClosing 5 /* connection is being torn down */ æC æKY sClosed æFc ADSP.h æT #define æD #define sClosed 6 /* connection end state is closed */ æC æKY eClosed æFc ADSP.h æT #define æD #define eClosed 0x80 /* received connection closed advice */ æC æKY eTearDown æFc ADSP.h æT #define æD #define eTearDown 0x40 /* connection closed due to broken connection */ æC æKY eAttention æFc ADSP.h æT #define æD #define eAttention 0x20 /* received attention message */ æC æKY eFwdReset æFc ADSP.h æT #define æD #define eFwdReset 0x10 /* received forward reset advice */ æC æKY attnBufSize æFc ADSP.h æT #define æD #define attnBufSize 570 /* size of client attention buffer */ æC æKY minDSPQueueSize æFc ADSP.h æT #define æD #define minDSPQueueSize 100 /* Minimum size of receive or send Queue */ æC æKY TRCCB TPCCB æFc ADSP.h æT struct æD struct TRCCB { unsigned char *ccbLink; /* link to next ccb */ unsigned short refNum; /* user reference number */ unsigned short state; /* state of the connection end */ unsigned char userFlags; /* flags for unsolicited connection events */ unsigned char localSocket; /* socket number of this connection end */ AddrBlock remoteAddress; /* internet address of remote end */ unsigned short attnCode; /* attention code received */ unsigned short attnSize; /* size of received attention data */ unsigned char *attnPtr; /* ptr to received attention data */ unsigned char reserved[220]; /* for adsp internal use */ }; typedef struct TRCCB TRCCB; typedef TRCCB *TPCCB; æC æKY TRinitParams æFc ADSP.h æT struct æD struct TRinitParams { TPCCB ccbPtr; /* pointer to connection control block */ ProcPtr userRoutine; /* client routine to call on event */ unsigned short sendQSize; /* size of send queue (0..64K bytes) */ unsigned char *sendQueue; /* client passed send queue buffer */ unsigned short recvQSize; /* size of receive queue (0..64K bytes) */ unsigned char *recvQueue; /* client passed receive queue buffer */ unsigned char *attnPtr; /* client passed receive attention buffer */ unsigned char localSocket; /* local socket number */ }; typedef struct TRinitParams TRinitParams; æC æKY TRopenParams æFc ADSP.h æT struct æD struct TRopenParams { unsigned short localCID; /* local connection id */ unsigned short remoteCID; /* remote connection id */ AddrBlock remoteAddress; /* address of remote end */ AddrBlock filterAddress; /* address filter */ unsigned long sendSeq; /* local send sequence number */ unsigned short sendWindow; /* send window size */ unsigned long recvSeq; /* receive sequence number */ unsigned long attnSendSeq; /* attention send sequence number */ unsigned long attnRecvSeq; /* attention receive sequence number */ unsigned char ocMode; /* open connection mode */ unsigned char ocInterval; /* open connection request retry interval */ unsigned char ocMaximum; /* open connection request retry maximum */ }; typedef struct TRopenParams TRopenParams; æC æKY TRcloseParams æFc ADSP.h æT struct æD struct TRcloseParams { unsigned char abort; /* abort connection immediately if non-zero */ }; typedef struct TRcloseParams TRcloseParams; æC æKY TRstatusParams æFc ADSP.h æT struct æD struct TRstatusParams { TPCCB ccbPtr; /* pointer to ccb */ unsigned short sendQPending; /* pending bytes in send queue */ unsigned short sendQFree; /* available buffer space in send queue */ unsigned short recvQPending; /* pending bytes in receive queue */ unsigned short recvQFree; /* available buffer space in receive queue */ }; typedef struct TRstatusParams TRstatusParams; æC æKY TRioParams æFc ADSP.h æT struct æD struct TRioParams { unsigned short reqCount; /* requested number of bytes */ unsigned short actCount; /* actual number of bytes */ unsigned char *dataPtr; /* pointer to data buffer */ unsigned char eom; /* indicates logical end of message */ unsigned char flush; /* send data now */ }; typedef struct TRioParams TRioParams; æC æKY TRattnParams æFc ADSP.h æT struct æD struct TRattnParams { unsigned short attnCode; /* client attention code */ unsigned short attnSize; /* size of attention data */ unsigned char *attnData; /* pointer to attention data */ unsigned char attnInterval; /* retransmit timer in 10-tick intervals */ }; typedef struct TRattnParams TRattnParams; æC æKY TRoptionParams æFc ADSP.h æT struct æD struct TRoptionParams { unsigned short sendBlocking; /* quantum for data packets */ unsigned char sendTimer; /* send timer in 10-tick intervals */ unsigned char rtmtTimer; /* retransmit timer in 10-tick intervals */ unsigned char badSeqMax; /* threshold for sending retransmit advice */ unsigned char useCheckSum; /* use ddp packet checksum */ }; typedef struct TRoptionParams TRoptionParams; æC æKY TRnewcidParams æFc ADSP.h æT struct æD struct TRnewcidParams { unsigned short newcid; /* new connection id returned */ }; typedef struct TRnewcidParams TRnewcidParams; æC æKY DSPParamBlock DSPPBPtr æFc ADSP.h æT struct æD struct DSPParamBlock { struct QElem *qLink; short qType; short ioTrap; Ptr ioCmdAddr; ProcPtr ioCompletion; OSErr ioResult; char *ioNamePtr; short ioVRefNum; short ioCRefNum; /* adsp driver refNum */ short csCode; /* adsp driver control code */ long qStatus; /* adsp internal use */ short ccbRefNum; /* connection end refNum */ union { TRinitParams initParams; /* dspInit, dspCLInit */ TRopenParams openParams; /* dspOpen, dspCLListen, dspCLDeny */ TRcloseParams closeParams; /* dspClose, dspRemove */ TRioParams ioParams; /* dspRead, dspWrite */ TRattnParams attnParams; /* dspAttention */ TRstatusParams statusParams; /* dspStatus */ TRoptionParams optionParams; /* dspOptions */ TRnewcidParams newCIDParams; /* dspNewCID */ } u; }; typedef struct DSPParamBlock DSPParamBlock; typedef struct DSPParamBlock *DSPPBPtr; æC æKY AIFF.h æKL ACE2to1Name ACE2Type ACE8to3Name ACE8Type AIFCID AIFCVersion1 AIFFID AIFFLoop AnnotationID ApplicationSpecificChunk ApplicationSpecificChunkPtr ApplicationSpecificID AudioRecordingChunk AudioRecordingChunkPtr AudioRecordingID AuthorID ChunkHeader Comment CommentID CommentsChunk CommentsChunkPtr CommonChunk CommonChunkPtr CommonID ContainerChunk CopyrightID ExtCommonChunk ExtCommonChunkPtr FormatVersionChunk FormatVersionChunkPtr FormatVersionID FORMID ForwardBackwardLooping ForwardLooping ID InstrumentChunk InstrumentChunkPtr InstrumentID MACE3to1Name MACE3Type MACE6to1Name MACE6Type Marker MarkerChunk MarkerChunkPtr MarkerID MarkerIdType MIDIDataChunk MIDIDataChunkPtr MIDIDataID NameID NoLooping NoneName NoneType SoundDataChunk SoundDataChunkPtr SoundDataID TextChunk TextChunkPtr æKY AIFFID æFc AIFF.h æT #define æD #define AIFFID 'AIFF' æC æKY AIFCID æFc AIFF.h æT #define æD #define AIFCID 'AIFC' æC æKY FormatVersionID æFc AIFF.h æT #define æD #define FormatVersionID 'FVER' æC æKY CommonID æFc AIFF.h æT #define æD #define CommonID 'COMM' æC æKY FORMID æFc AIFF.h æT #define æD #define FORMID 'FORM' æC æKY SoundDataID æFc AIFF.h æT #define æD #define SoundDataID 'SSND' æC æKY MarkerID æFc AIFF.h æT #define æD #define MarkerID 'MARK' æC æKY InstrumentID æFc AIFF.h æT #define æD #define InstrumentID 'INST' æC æKY MIDIDataID æFc AIFF.h æT #define æD #define MIDIDataID 'MIDI' æC æKY AudioRecordingID æFc AIFF.h æT #define æD #define AudioRecordingID 'AESD' æC æKY ApplicationSpecificID æFc AIFF.h æT #define æD #define ApplicationSpecificID 'APPL' æC æKY CommentID æFc AIFF.h æT #define æD #define CommentID 'COMT' æC æKY NameID æFc AIFF.h æT #define æD #define NameID 'NAME' æC æKY AuthorID æFc AIFF.h æT #define æD #define AuthorID 'AUTH' æC æKY CopyrightID æFc AIFF.h æT #define æD #define CopyrightID '(c) ' æC æKY AnnotationID æFc AIFF.h æT #define æD #define AnnotationID 'ANNO' æC æKY NoLooping æFc AIFF.h æT æD NoLooping = 0, æC æKY ForwardLooping æFc AIFF.h æT æD ForwardLooping = 1, æC æKY ForwardBackwardLooping æFc AIFF.h æT æD ForwardBackwardLooping = 2, æC æKY AIFCVersion1 æFc AIFF.h æT æD AIFCVersion1 = 0xA2805140, æC æKY NoneName æFc AIFF.h æT #define æD #define NoneName "\pnot compressed" æC æKY ACE2to1Name æFc AIFF.h æT #define æD #define ACE2to1Name "\pACE 2-to-1" æC æKY ACE8to3Name æFc AIFF.h æT #define æD #define ACE8to3Name "\pACE 8-to-3" æC æKY MACE3to1Name æFc AIFF.h æT #define æD #define MACE3to1Name "\pMACE 3-to-1" æC æKY MACE6to1Name æFc AIFF.h æT #define æD #define MACE6to1Name "\pMACE 6-to-1" æC æKY NoneType æFc AIFF.h æT #define æD #define NoneType 'NONE' æC æKY ACE2Type æFc AIFF.h æT #define æD #define ACE2Type 'ACE2' æC æKY ACE8Type æFc AIFF.h æT #define æD #define ACE8Type 'ACE8' æC æKY MACE3Type æFc AIFF.h æT #define æD #define MACE3Type 'MAC3' æC æKY MACE6Type æFc AIFF.h æT #define æD #define MACE6Type 'MAC6' æC æKY ID æFc AIFF.h æT typedef æD typedef unsigned long ID; æC æKY MarkerIdType æFc AIFF.h æT typedef æD typedef short MarkerIdType; æC æKY ChunkHeader æFc AIFF.h æT struct æD struct ChunkHeader { ID ckID; long ckSize; }; typedef struct ChunkHeader ChunkHeader; æC æKY ContainerChunk æFc AIFF.h æT struct æD struct ContainerChunk { ID ckID; long ckSize; ID formType; }; typedef struct ContainerChunk ContainerChunk; æC æKY FormatVersionChunk FormatVersionChunkPtr æFc AIFF.h æT struct æD struct FormatVersionChunk { ID ckID; long ckSize; unsigned long timestamp; }; typedef struct FormatVersionChunk FormatVersionChunk; typedef FormatVersionChunk *FormatVersionChunkPtr; æC æKY CommonChunk CommonChunkPtr æFc AIFF.h æT struct æD struct CommonChunk { ID ckID; long ckSize; short numChannels; unsigned long numSampleFrames; short sampleSize; extended sampleRate; }; typedef struct CommonChunk CommonChunk; typedef CommonChunk *CommonChunkPtr; æC æKY ExtCommonChunk ExtCommonChunkPtr æFc AIFF.h æT struct æD struct ExtCommonChunk { ID ckID; long ckSize; short numChannels; unsigned long numSampleFrames; short sampleSize; extended sampleRate; ID compressionType; char compressionName[1]; }; typedef struct ExtCommonChunk ExtCommonChunk; typedef ExtCommonChunk *ExtCommonChunkPtr; æC æKY SoundDataChunk SoundDataChunkPtr æFc AIFF.h æT struct æD struct SoundDataChunk { ID ckID; long ckSize; unsigned long offset; unsigned long blockSize; }; typedef struct SoundDataChunk SoundDataChunk; typedef SoundDataChunk *SoundDataChunkPtr; æC æKY Marker æFc AIFF.h æT struct æD struct Marker { MarkerIdType id; unsigned long position; Str255 markerName; }; typedef struct Marker Marker; æC æKY MarkerChunk MarkerChunkPtr æFc AIFF.h æT struct æD struct MarkerChunk { ID ckID; long ckSize; unsigned short numMarkers; Marker Markers[1]; }; typedef struct MarkerChunk MarkerChunk; typedef MarkerChunk *MarkerChunkPtr; æC æKY AIFFLoop æFc AIFF.h æT struct æD struct AIFFLoop { short playMode; MarkerIdType beginLoop; MarkerIdType endLoop; }; typedef struct AIFFLoop AIFFLoop; æC æKY InstrumentChunk InstrumentChunkPtr æFc AIFF.h æT struct æD struct InstrumentChunk { ID ckID; long ckSize; char baseFrequency; char detune; char lowFrequency; char highFrequency; char lowVelocity; char highVelocity; short gain; AIFFLoop sustainLoop; AIFFLoop releaseLoop; }; typedef struct InstrumentChunk InstrumentChunk; typedef InstrumentChunk *InstrumentChunkPtr; æC æKY MIDIDataChunk MIDIDataChunkPtr æFc AIFF.h æT struct æD struct MIDIDataChunk { ID ckID; long ckSize; unsigned char MIDIdata[1]; }; typedef struct MIDIDataChunk MIDIDataChunk; typedef MIDIDataChunk *MIDIDataChunkPtr; æC æKY AudioRecordingChunk AudioRecordingChunkPtr æFc AIFF.h æT struct æD struct AudioRecordingChunk { ID ckID; long ckSize; unsigned char AESChannelStatus[24]; }; typedef struct AudioRecordingChunk AudioRecordingChunk; typedef AudioRecordingChunk *AudioRecordingChunkPtr; æC æKY ApplicationSpecificChunk ApplicationSpecificChunkPtr æFc AIFF.h æT struct æD struct ApplicationSpecificChunk { ID ckID; long ckSize; OSType applicationSignature; char data[1]; }; typedef struct ApplicationSpecificChunk ApplicationSpecificChunk; typedef ApplicationSpecificChunk *ApplicationSpecificChunkPtr; æC æKY Comment æFc AIFF.h æT struct æD struct Comment { unsigned long timeStamp; MarkerIdType marker; unsigned short count; char text[1]; }; typedef struct Comment Comment; æC æKY CommentsChunk CommentsChunkPtr æFc AIFF.h æT struct æD struct CommentsChunk { ID ckID; long ckSize; unsigned short numComments; Comment comments[1]; }; typedef struct CommentsChunk CommentsChunk; typedef CommentsChunk *CommentsChunkPtr; æC æKY TextChunk TextChunkPtr æFc AIFF.h æT struct æD struct TextChunk { ID ckID; long ckSize; char text[1]; }; typedef struct TextChunk TextChunk; typedef TextChunk *TextChunkPtr; æC æKY Aliases.h æKL GetAliasInfo MatchAlias NewAlias NewAliasMinimal NewAliasMinimalFromFullPath ResolveAlias ResolveAliasFile UpdateAlias AliasFilterProcPtr AliasHandle AliasInfoType AliasPtr AliasRecord asiAliasName asiParentName asiServerName asiVolumeName asiZoneName kARMMountVol kARMMultVols kARMNoUI kARMSearch kARMSearchMore kARMSearchRelFirst rAliasType æKY rAliasType æFc Aliases.h æT #define æD #define rAliasType 'alis' /* Aliases are stored as resources of this type */ æC æKY kARMMountVol æFc Aliases.h æT æD kARMMountVol = 0x00000001, /* mount the volume automatically */ æC æKY kARMNoUI æFc Aliases.h æT æD kARMNoUI = 0x00000002, /* no user interface allowed during resolution */ æC æKY kARMMultVols æFc Aliases.h æT æD kARMMultVols = 0x00000008, /* search on multiple volumes */ æC æKY kARMSearch æFc Aliases.h æT æD kARMSearch = 0x00000100, /* search quickly */ æC æKY kARMSearchMore æFc Aliases.h æT æD kARMSearchMore = 0x00000200, /* search further */ æC æKY kARMSearchRelFirst æFc Aliases.h æT æD kARMSearchRelFirst = 0x00000400, /* search target on a relative path first */ æC æKY asiZoneName æFc Aliases.h æT æD asiZoneName = -3, /* get zone name */ æC æKY asiServerName æFc Aliases.h æT æD asiServerName = -2, /* get server name */ æC æKY asiVolumeName æFc Aliases.h æT æD asiVolumeName = -1, /* get volume name */ æC æKY asiAliasName æFc Aliases.h æT æD asiAliasName = 0, /* get aliased file/folder/volume name */ æC æKY asiParentName æFc Aliases.h æT æD asiParentName = 1, /* get parent folder name */ æC æKY AliasRecord AliasPtr AliasHandle æFc Aliases.h æT struct æD struct AliasRecord { OSType userType; /* appl stored type like creator type */ unsigned short aliasSize; /* alias record size in bytes, for appl usage */ }; typedef struct AliasRecord AliasRecord; typedef AliasRecord *AliasPtr, **AliasHandle; æC æKY AliasInfoType æFc Aliases.h æT typedef æD typedef short AliasInfoType; /* alias record information type */ æC æKY AliasFilterProcPtr æFc Aliases.h æT typedef æD typedef pascal Boolean (*AliasFilterProcPtr) (CInfoPBPtr cpbPtr, /*I*/ Boolean *quitFlag, /*O*/ Ptr yourDataPtr); /*I*/ æC æKY NewAlias æFc Aliases.h æT Function æTN A823 æD pascal OSErr NewAlias(const FSSpec *fromFile, const FSSpec *target, AliasHandle *alias) = {0x7002,0xA823}; æDT OSErr myVariable = NewAlias((const FSSpec *) fromFile,( const FSSpec) * target,( AliasHandle) * alias); æC æKY NewAliasMinimal æFc Aliases.h æT Function æTN A823 æD pascal OSErr NewAliasMinimal(const FSSpec *target, AliasHandle *alias) = {0x7008,0xA823}; æDT OSErr myVariable = NewAliasMinimal((const FSSpec *) target,( AliasHandle) * alias); æC æKY NewAliasMinimalFromFullPath æFc Aliases.h æT Function æTN A823 æD pascal OSErr NewAliasMinimalFromFullPath(short fullPathLength, const unsigned char *fullPath, ConstStr32Param zoneName, ConstStr31Param serverName, AliasHandle *alias) = {0x7009,0xA823}; #define NewAliasMinimalFromFullpath NewAliasMinimalFromFullPath æDT OSErr myVariable = NewAliasMinimalFromFullPath((short) fullPathLength,( const unsigned char) * fullPath,() ConstStr32Param zoneName,() ConstStr31Param serverName,( AliasHandle) * alias); æC æKY ResolveAlias æFc Aliases.h æT Function æTN A823 æD pascal OSErr ResolveAlias(const FSSpec *fromFile, AliasHandle alias, FSSpec *target, Boolean *wasChanged) = {0x7003,0xA823}; æDT OSErr myVariable = ResolveAlias((const FSSpec *) fromFile,() AliasHandle alias,( FSSpec) * target,( Boolean) * wasChanged); æC æKY GetAliasInfo æFc Aliases.h æT Function æTN A823 æD pascal OSErr GetAliasInfo(const AliasHandle alias, AliasInfoType index, Str63 theString) = {0x7007,0xA823}; æDT OSErr myVariable = GetAliasInfo((const AliasHandle) alias,() AliasInfoType index,() Str63 theString); æC æKY ResolveAliasFile æFc Aliases.h æT Function æTN A823 æD pascal OSErr ResolveAliasFile(FSSpec *theSpec, Boolean resolveAliasChains, Boolean *targetIsFolder, Boolean *wasAliased) = {0x700C,0xA823}; æDT OSErr myVariable = ResolveAliasFile((FSSpec *) theSpec,() Boolean resolveAliasChains,( Boolean) * targetIsFolder,( Boolean) * wasAliased); æC æKY MatchAlias æFc Aliases.h æT Function æTN A823 æD pascal OSErr MatchAlias(const FSSpec *fromFile, unsigned long rulesMask, const AliasHandle alias, short *aliasCount, FSSpecArrayPtr aliasList, Boolean *needsUpdate, AliasFilterProcPtr aliasFilter, void *yourDataPtr) = {0x7005,0xA823}; æDT OSErr myVariable = MatchAlias((const FSSpec *) fromFile,( unsigned) long rulesMask,( const) AliasHandle alias,( short) * aliasCount,() FSSpecArrayPtr aliasList,( Boolean) * needsUpdate,() AliasFilterProcPtr aliasFilter,( void) * yourDataPtr); æC æKY UpdateAlias æFc Aliases.h æT Function æTN A823 æD pascal OSErr UpdateAlias(const FSSpec *fromFile, const FSSpec *target, AliasHandle alias, Boolean *wasChanged) = {0x7006,0xA823}; æDT OSErr myVariable = UpdateAlias((const FSSpec *) fromFile,( const FSSpec) * target,() AliasHandle alias,( Boolean) * wasChanged); æC æKY AppleEvents.h æKL AECoerceDesc AECoercePtr AECountItems AECreateAppleEvent AECreateDesc AECreateList AEDeleteItem AEDeleteKeyDesc AEDeleteParam AEDisposeDesc AEDuplicateDesc AEGetArray AEGetAttributeDesc AEGetAttributePtr AEGetCoercionHandler AEGetEventHandler AEGetInteractionAllowed AEGetKeyDesc AEGetKeyPtr AEGetNthDesc AEGetNthPtr AEGetParamDesc AEGetParamPtr AEGetSpecialHandler AEGetTheCurrentEvent AEInstallCoercionHandler AEInstallEventHandler AEInstallSpecialHandler AEInteractWithUser AEProcessAppleEvent AEPutArray AEPutAttributeDesc AEPutAttributePtr AEPutDesc AEPutKeyDesc AEPutKeyPtr AEPutParamDesc AEPutParamPtr AEPutPtr AERemoveCoercionHandler AERemoveEventHandler AERemoveSpecialHandler AEResetTimer AEResumeTheCurrentEvent AESend AESetInteractionAllowed AESetTheCurrentEvent AESizeOfAttribute AESizeOfKeyDesc AESizeOfNthItem AESizeOfParam AESuspendTheCurrentEvent AEAddressDesc AEArrayData AEArrayDataPointer AEArrayType AEDesc AEDescList AEEventClass AEEventID AEEventSource AEInteractAllowed AEKeyDesc AEKeyword AERecord AESendMode AESendPriority AppleEvent DescType errAEBadListItem errAECoercionFail errAECorruptData errAEDescNotFound errAEEventNotHandled errAEHandlerNotFound errAEIllegalIndex errAENewerVersion errAENotAEDesc errAENotAppleEvent errAENotASpecialFunction errAENoUserInteraction errAEParamMissed errAEReplyNotArrived errAEReplyNotValid errAETimeout errAEUnknownAddressType errAEUnknownSendMode errAEWaitCanceled errAEWrongDataType EventFilterProcPtr EventHandlerProcPtr IdleProcPtr kAEAlwaysInteract kAEAnswer kAEApplicationDied kAECanInteract kAECanSwitchLayer kAECreatorType kAEDataArray kAEDefaultTimeout kAEDescArray kAEDirectCall kAEDontReconnect kAEHandleArray kAEHighPriority kAEInteractWithAll kAEInteractWithLocal kAEInteractWithSelf kAEKeyDescArray kAELocalProcess kAENeverInteract kAENoDispatch kAENoReply kAENormalPriority kAEOpenApplication kAEOpenDocuments kAEPackedArray kAEPrintDocuments kAEQueueReply kAEQuitAll kAEQuitApplication kAERemoteProcess kAERestart kAESameProcess kAEShutDown kAEUnknownSource kAEUseStandardDispatch kAEWaitReply kAEWantReceipt kAnyTransactionID kAutoGenerateReturnID kCoreEventClass keyAddressAttr keyDirectObject keyErrorNumber keyErrorString keyEventClassAttr keyEventIDAttr keyEventSourceAttr keyInteractLevelAttr keyMissedKeywordAttr keyOptionalKeywordAttr keyPreDispatch keyProcessSerialNumber keyReturnIDAttr keySelectProc keyTimeoutAttr keyTransactionIDAttr kNoTimeOut typeAEList typeAERecord typeAlias typeApplSignature typeAppParameters typeBoolean typeChar typeComp typeEnumerated typeExtended typeFalse typeFloat typeFSS typeInteger typeKeyword typeLongFloat typeLongInteger typeMagnitude typeNull typeProcessSerialNumber typeProperty typeSectionH typeSessionID typeShortFloat typeShortInteger typeSMFloat typeSMInt typeTargetID typeTrue typeType typeWildCard æKY typeBoolean æFc AppleEvents.h æT #define æD #define typeBoolean 'bool' æC æKY typeChar æFc AppleEvents.h æT #define æD #define typeChar 'TEXT' æC æKY typeSMInt æFc AppleEvents.h æT #define æD #define typeSMInt 'shor' æC æKY typeInteger æFc AppleEvents.h æT #define æD #define typeInteger 'long' æC æKY typeSMFloat æFc AppleEvents.h æT #define æD #define typeSMFloat 'sing' æC æKY typeFloat æFc AppleEvents.h æT #define æD #define typeFloat 'doub' æC æKY typeLongInteger æFc AppleEvents.h æT #define æD #define typeLongInteger 'long' æC æKY typeShortInteger æFc AppleEvents.h æT #define æD #define typeShortInteger 'shor' æC æKY typeLongFloat æFc AppleEvents.h æT #define æD #define typeLongFloat 'doub' æC æKY typeShortFloat æFc AppleEvents.h æT #define æD #define typeShortFloat 'sing' æC æKY typeExtended æFc AppleEvents.h æT #define æD #define typeExtended 'exte' æC æKY typeComp æFc AppleEvents.h æT #define æD #define typeComp 'comp' æC æKY typeMagnitude æFc AppleEvents.h æT #define æD #define typeMagnitude 'magn' æC æKY typeAEList æFc AppleEvents.h æT #define æD #define typeAEList 'list' æC æKY typeAERecord æFc AppleEvents.h æT #define æD #define typeAERecord 'reco' æC æKY typeTrue æFc AppleEvents.h æT #define æD #define typeTrue 'true' æC æKY typeFalse æFc AppleEvents.h æT #define æD #define typeFalse 'fals' æC æKY typeAlias æFc AppleEvents.h æT #define æD #define typeAlias 'alis' æC æKY typeEnumerated æFc AppleEvents.h æT #define æD #define typeEnumerated 'enum' æC æKY typeType æFc AppleEvents.h æT #define æD #define typeType 'type' æC æKY typeAppParameters æFc AppleEvents.h æT #define æD #define typeAppParameters 'appa' æC æKY typeProperty æFc AppleEvents.h æT #define æD #define typeProperty 'prop' æC æKY typeFSS æFc AppleEvents.h æT #define æD #define typeFSS 'fss ' æC æKY typeKeyword æFc AppleEvents.h æT #define æD #define typeKeyword 'keyw' æC æKY typeSectionH æFc AppleEvents.h æT #define æD #define typeSectionH 'sect' æC æKY typeWildCard æFc AppleEvents.h æT #define æD #define typeWildCard '****' æC æKY typeApplSignature æFc AppleEvents.h æT #define æD #define typeApplSignature 'sign' æC æKY typeSessionID æFc AppleEvents.h æT #define æD #define typeSessionID 'ssid' æC æKY typeTargetID æFc AppleEvents.h æT #define æD #define typeTargetID 'targ' æC æKY typeProcessSerialNumber æFc AppleEvents.h æT #define æD #define typeProcessSerialNumber 'psn ' æC æKY typeNull æFc AppleEvents.h æT #define æD #define typeNull 'null' /*the type of null/nonexistent data*/ æC æKY kCoreEventClass æFc AppleEvents.h æT #define æD #define kCoreEventClass 'aevt' æC æKY kAEOpenApplication æFc AppleEvents.h æT #define æD #define kAEOpenApplication 'oapp' æC æKY kAEOpenDocuments æFc AppleEvents.h æT #define æD #define kAEOpenDocuments 'odoc' æC æKY kAEPrintDocuments æFc AppleEvents.h æT #define æD #define kAEPrintDocuments 'pdoc' æC æKY kAEQuitApplication æFc AppleEvents.h æT #define æD #define kAEQuitApplication 'quit' æC æKY kAECreatorType æFc AppleEvents.h æT #define æD #define kAECreatorType 'crea' æC æKY kAEQuitAll æFc AppleEvents.h æT #define æD #define kAEQuitAll 'quia' æC æKY kAEShutDown æFc AppleEvents.h æT #define æD #define kAEShutDown 'shut' æC æKY kAERestart æFc AppleEvents.h æT #define æD #define kAERestart 'rest' æC æKY kAEApplicationDied æFc AppleEvents.h æT #define æD #define kAEApplicationDied 'obit' æC æKY keyProcessSerialNumber æFc AppleEvents.h æT #define æD #define keyProcessSerialNumber 'psn ' æC æKY keyErrorNumber æFc AppleEvents.h æT #define æD #define keyErrorNumber 'errn' æC æKY keyErrorString æFc AppleEvents.h æT #define æD #define keyErrorString 'errs' æC æKY kAEAnswer æFc AppleEvents.h æT #define æD #define kAEAnswer 'ansr' æC æKY keyDirectObject æFc AppleEvents.h æT #define æD #define keyDirectObject '----' æC æKY keyPreDispatch æFc AppleEvents.h æT #define æD #define keyPreDispatch 'phac' /* PreHandler Accessor Call */ æC æKY keySelectProc æFc AppleEvents.h æT #define æD #define keySelectProc 'selh' /* More selector Call */ æC æKY keyTransactionIDAttr æFc AppleEvents.h æT #define æD #define keyTransactionIDAttr 'tran' æC æKY keyReturnIDAttr æFc AppleEvents.h æT #define æD #define keyReturnIDAttr 'rtid' æC æKY keyEventClassAttr æFc AppleEvents.h æT #define æD #define keyEventClassAttr 'evcl' æC æKY keyEventIDAttr æFc AppleEvents.h æT #define æD #define keyEventIDAttr 'evid' æC æKY keyAddressAttr æFc AppleEvents.h æT #define æD #define keyAddressAttr 'addr' æC æKY keyOptionalKeywordAttr æFc AppleEvents.h æT #define æD #define keyOptionalKeywordAttr 'optk' æC æKY keyTimeoutAttr æFc AppleEvents.h æT #define æD #define keyTimeoutAttr 'timo' æC æKY keyInteractLevelAttr æFc AppleEvents.h æT #define æD #define keyInteractLevelAttr 'inte' /*this attribute is read only will be set in AESend*/ æC æKY keyEventSourceAttr æFc AppleEvents.h æT #define æD #define keyEventSourceAttr 'esrc' /* this attribute is read only */ æC æKY keyMissedKeywordAttr æFc AppleEvents.h æT #define æD #define keyMissedKeywordAttr 'miss' /* this attribute is read only */ æC æKY kAENoReply æFc AppleEvents.h æT æD kAENoReply = 0x00000001, /* Sender doesn't want a reply to event */ æC æKY kAEQueueReply æFc AppleEvents.h æT æD kAEQueueReply = 0x00000002, /* Sender wants a reply but won't wait */ æC æKY kAEWaitReply æFc AppleEvents.h æT æD kAEWaitReply = 0x00000003, /* Sender wants a reply and will be waiting */ æC æKY kAENeverInteract æFc AppleEvents.h æT æD kAENeverInteract = 0x00000010, /* Server should not interact with user */ æC æKY kAECanInteract æFc AppleEvents.h æT æD kAECanInteract = 0x00000020, /* Server may try to interact with user */ æC æKY kAEAlwaysInteract æFc AppleEvents.h æT æD kAEAlwaysInteract = 0x00000030, /* Server should always interact with user where appropriate */ æC æKY kAECanSwitchLayer æFc AppleEvents.h æT æD kAECanSwitchLayer = 0x00000040, /* Interaction may switch layer */ æC æKY kAEDontReconnect æFc AppleEvents.h æT æD kAEDontReconnect = 0x00000080, /* don't reconnect if there is a sessClosedErr from PPCToolbox */ æC æKY kAEWantReceipt æFc AppleEvents.h æT #define æD #define kAEWantReceipt nReturnReceipt /* Send wants a receipt of message */ æC æKY kAENormalPriority æFc AppleEvents.h æT æD kAENormalPriority = 0x00000000, /* Post message at the end of event queue */ æC æKY kAEHighPriority æFc AppleEvents.h æT #define æD #define kAEHighPriority nAttnMsg /* Post message at the front of the event queue */ æC æKY kAnyTransactionID æFc AppleEvents.h æT æD kAnyTransactionID = 0, /* no transaction is in use */ æC æKY kAutoGenerateReturnID æFc AppleEvents.h æT æD kAutoGenerateReturnID = -1, /* AECreateAppleEvent will generate a session-unique ID */ æC æKY kAEDefaultTimeout æFc AppleEvents.h æT æD kAEDefaultTimeout = -1, /* timeout value determined by AEM */ æC æKY kNoTimeOut æFc AppleEvents.h æT æD kNoTimeOut = -2, /* wait until reply comes back, however long it takes */ æC æKY kAENoDispatch æFc AppleEvents.h æT æD kAENoDispatch = 0, æC æKY kAEUseStandardDispatch æFc AppleEvents.h æT æD kAEUseStandardDispatch = -1, æC æKY errAECoercionFail æFc AppleEvents.h æT æD errAECoercionFail = -1700, æC æKY errAEDescNotFound æFc AppleEvents.h æT æD errAEDescNotFound = -1701, æC æKY errAECorruptData æFc AppleEvents.h æT æD errAECorruptData = -1702, æC æKY errAEWrongDataType æFc AppleEvents.h æT æD errAEWrongDataType = -1703, æC æKY errAENotAEDesc æFc AppleEvents.h æT æD errAENotAEDesc = -1704, æC æKY errAEBadListItem æFc AppleEvents.h æT æD errAEBadListItem = -1705, /* Specified list item does not exist */ æC æKY errAENewerVersion æFc AppleEvents.h æT æD errAENewerVersion = -1706, /* Need newer version of AppleEvent Manager */ æC æKY errAENotAppleEvent æFc AppleEvents.h æT æD errAENotAppleEvent = -1707, /* The event is not in AppleEvent format */ æC æKY errAEEventNotHandled æFc AppleEvents.h æT æD errAEEventNotHandled = -1708, /* The AppleEvent was not handled by any handler */ æC æKY errAEReplyNotValid æFc AppleEvents.h æT æD errAEReplyNotValid = -1709, /* AEResetTimer was passed an invalid reply parameter */ æC æKY errAEUnknownSendMode æFc AppleEvents.h æT æD errAEUnknownSendMode = -1710, /* Mode wasn't NoReply, WaitReply, or QueueReply; or Interaction level is unknown */ æC æKY errAEWaitCanceled æFc AppleEvents.h æT æD errAEWaitCanceled = -1711, /* In AESend, User cancelled out of wait loop for reply or receipt */ æC æKY errAETimeout æFc AppleEvents.h æT æD errAETimeout = -1712, /* AppleEvent timed out */ æC æKY errAENoUserInteraction æFc AppleEvents.h æT æD errAENoUserInteraction = -1713, /* no user interaction allowed */ æC æKY errAENotASpecialFunction æFc AppleEvents.h æT æD errAENotASpecialFunction = -1714, /* there is no special function with this keyword */ æC æKY errAEParamMissed æFc AppleEvents.h æT æD errAEParamMissed = -1715, /* a required parameter was not accessed */ æC æKY errAEUnknownAddressType æFc AppleEvents.h æT æD errAEUnknownAddressType = -1716, /* The target address type is not known */ æC æKY errAEHandlerNotFound æFc AppleEvents.h æT æD errAEHandlerNotFound = -1717, /* No handler in the dispatch tables fits the parameters to AEGetEventHandler or AEGetCoercionHandler */ æC æKY errAEReplyNotArrived æFc AppleEvents.h æT æD errAEReplyNotArrived = -1718, /* the contents of the reply you are accessing have not arrived yet */ æC æKY errAEIllegalIndex æFc AppleEvents.h æT æD errAEIllegalIndex = -1719, /* Index is out of range in a put operation */ æC æKY AEKeyword æFc AppleEvents.h æT typedef æD typedef unsigned long AEKeyword; æC æKY AEEventClass æFc AppleEvents.h æT typedef æD typedef unsigned long AEEventClass; æC æKY AEEventID æFc AppleEvents.h æT typedef æD typedef unsigned long AEEventID; æC æKY DescType æFc AppleEvents.h æT typedef æD typedef ResType DescType; æC æKY AEDesc æFc AppleEvents.h æT struct æD struct AEDesc { DescType descriptorType; Handle dataHandle; }; typedef struct AEDesc AEDesc; æC æKY AEAddressDesc æFc AppleEvents.h æT typedef æD typedef AEDesc AEAddressDesc; /* an AEDesc which contains addressing data */ æC æKY AEDescList æFc AppleEvents.h æT typedef æD typedef AEDesc AEDescList; /* a list of AEDesc is a special kind of AEDesc */ æC æKY AERecord æFc AppleEvents.h æT typedef æD typedef AEDescList AERecord; /* AERecord is a list of keyworded AEDesc */ æC æKY AppleEvent æFc AppleEvents.h æT typedef æD typedef AERecord AppleEvent; /* an AERecord that contains an AppleEvent */ æC æKY AESendMode æFc AppleEvents.h æT typedef æD typedef long AESendMode; /* Type of parameter to AESend */ æC æKY AESendPriority æFc AppleEvents.h æT typedef æD typedef short AESendPriority; /* Type of priority param of AESend */ æC æKY AEInteractAllowed kAEInteractWithSelf kAEInteractWithLocal kAEInteractWithAll æFc AppleEvents.h æT enum æD enum {kAEInteractWithSelf,kAEInteractWithLocal,kAEInteractWithAll}; typedef unsigned char AEInteractAllowed; æC æKY AEEventSource kAEUnknownSource kAEDirectCall kAESameProcess kAELocalProcess kAERemoteProcess æFc AppleEvents.h æT enum æD enum {kAEUnknownSource,kAEDirectCall,kAESameProcess,kAELocalProcess,kAERemoteProcess}; typedef unsigned char AEEventSource; æC æKY AEKeyDesc æFc AppleEvents.h æT struct æD struct AEKeyDesc { AEKeyword descKey; AEDesc descContent; }; typedef struct AEKeyDesc AEKeyDesc; æC æKY AEArrayType kAEDataArray kAEPackedArray kAEHandleArray kAEDescArray kAEKeyDescArray æFc AppleEvents.h æT enum æD enum {kAEDataArray,kAEPackedArray,kAEHandleArray,kAEDescArray,kAEKeyDescArray}; typedef unsigned char AEArrayType; æC æKY AEArrayData AEArrayDataPointer æFc AppleEvents.h æT struct æD union AEArrayData { short AEDataArray[1]; char AEPackedArray[1]; Handle AEHandleArray[1]; AEDesc AEDescArray[1]; AEKeyDesc AEKeyDescArray[1]; }; typedef union AEArrayData AEArrayData; typedef AEArrayData *AEArrayDataPointer; æC æKY EventHandlerProcPtr æFc AppleEvents.h æT typedef æD typedef ProcPtr EventHandlerProcPtr; æC æKY IdleProcPtr æFc AppleEvents.h æT typedef æD typedef ProcPtr IdleProcPtr; æC æKY EventFilterProcPtr æFc AppleEvents.h æT typedef æD typedef ProcPtr EventFilterProcPtr; æC æKY AECreateDesc æFc AppleEvents.h æT Function æD pascal OSErr AECreateDesc(DescType typeCode, Ptr dataPtr, Size dataSize, AEDesc *result) = {0x303C,0x0825,0xA816}; æDT OSErr myVariable = AECreateDesc((DescType) typeCode,() Ptr dataPtr,() Size dataSize,( AEDesc) * result); æC æKY AECoercePtr æFc AppleEvents.h æT Function æD pascal OSErr AECoercePtr(DescType typeCode, Ptr dataPtr, Size dataSize, DescType toType, AEDesc *result) = {0x303C,0x0A02,0xA816}; æDT OSErr myVariable = AECoercePtr((DescType) typeCode,() Ptr dataPtr,() Size dataSize,() DescType toType,( AEDesc) * result); æC æKY AECoerceDesc æFc AppleEvents.h æT Function æD pascal OSErr AECoerceDesc(AEDesc theAEDesc, DescType toType, AEDesc *result) = {0x303C,0x0603,0xA816}; æDT OSErr myVariable = AECoerceDesc((AEDesc) theAEDesc,() DescType toType,( AEDesc) * result); æC æKY AEDisposeDesc æFc AppleEvents.h æT Function æD pascal OSErr AEDisposeDesc(AEDesc *theAEDesc) = {0x303C,0x0204,0xA816}; æDT OSErr myVariable = AEDisposeDesc((AEDesc *) theAEDesc); æC æKY AEDuplicateDesc æFc AppleEvents.h æT Function æD pascal OSErr AEDuplicateDesc(AEDesc theAEDesc,AEDesc *result) = {0x303C,0x0405,0xA816}; æDT OSErr myVariable = AEDuplicateDesc((AEDesc) theAEDesc,(AEDesc *) result); æC æKY AECreateList æFc AppleEvents.h æT Function æD pascal OSErr AECreateList(Ptr factoringPtr, Size factoredSize, Boolean isRecord, AEDescList *resultList) = {0x303C,0x0706,0xA816}; æDT OSErr myVariable = AECreateList((Ptr) factoringPtr,() Size factoredSize,() Boolean isRecord,( AEDescList) * resultList); æC æKY AECountItems æFc AppleEvents.h æT Function æD pascal OSErr AECountItems(AEDescList theAEDescList, long *theCount) = {0x303C,0x0407,0xA816}; æDT OSErr myVariable = AECountItems((AEDescList) theAEDescList,( long) * theCount); æC æKY AEPutPtr æFc AppleEvents.h æT Function æD pascal OSErr AEPutPtr(AEDescList theAEDescList, long index, DescType typeCode, Ptr dataPtr, Size dataSize) = {0x303C,0x0A08,0xA816}; æDT OSErr myVariable = AEPutPtr((AEDescList) theAEDescList,() long index,() DescType typeCode,() Ptr dataPtr,() Size dataSize); æC æKY AEPutDesc æFc AppleEvents.h æT Function æD pascal OSErr AEPutDesc(AEDescList theAEDescList, long index, AEDesc theAEDesc) = {0x303C,0x0609,0xA816}; æDT OSErr myVariable = AEPutDesc((AEDescList) theAEDescList,() long index,() AEDesc theAEDesc); æC æKY AEGetNthPtr æFc AppleEvents.h æT Function æD pascal OSErr AEGetNthPtr(AEDescList theAEDescList, long index, DescType desiredType, AEKeyword *theAEKeyword, DescType *typeCode, Ptr dataPtr, Size maximumSize, Size *actualSize) = {0x303C,0x100A,0xA816}; æDT OSErr myVariable = AEGetNthPtr((AEDescList) theAEDescList,() long index,() DescType desiredType,( AEKeyword) * theAEKeyword,( DescType) * typeCode,() Ptr dataPtr,() Size maximumSize,( Size) * actualSize); æC æKY AEGetNthDesc æFc AppleEvents.h æT Function æD pascal OSErr AEGetNthDesc(AEDescList theAEDescList, long index, DescType desiredType, AEKeyword *theAEKeyword, AEDesc *result) = {0x303C,0x0A0B,0xA816}; æDT OSErr myVariable = AEGetNthDesc((AEDescList) theAEDescList,() long index,() DescType desiredType,( AEKeyword) * theAEKeyword,( AEDesc) * result); æC æKY AESizeOfNthItem æFc AppleEvents.h æT Function æD pascal OSErr AESizeOfNthItem(AEDescList theAEDescList, long index, DescType *typeCode, Size *dataSize) = {0x303C,0x082A,0xA816}; æDT OSErr myVariable = AESizeOfNthItem((AEDescList) theAEDescList,() long index,( DescType) * typeCode,( Size) * dataSize); æC æKY AEGetArray æFc AppleEvents.h æT Function æD pascal OSErr AEGetArray(AEDescList theAEDescList, AEArrayType arrayType, AEArrayDataPointer arrayPtr, Size maximumSize, DescType *itemType, Size *itemSize, long *itemCount) = {0x303C,0x0D0C,0xA816}; æDT OSErr myVariable = AEGetArray((AEDescList) theAEDescList,() AEArrayType arrayType,() AEArrayDataPointer arrayPtr,() Size maximumSize,( DescType) * itemType,( Size) * itemSize,( long) * itemCount); æC æKY AEPutArray æFc AppleEvents.h æT Function æD pascal OSErr AEPutArray(AEDescList theAEDescList, AEArrayType arrayType, AEArrayDataPointer arrayPtr, DescType itemType, Size itemSize, long itemCount) = {0x303C,0x0B0D,0xA816}; æDT OSErr myVariable = AEPutArray((AEDescList) theAEDescList,() AEArrayType arrayType,() AEArrayDataPointer arrayPtr,() DescType itemType,() Size itemSize,() long itemCount); æC æKY AEDeleteItem æFc AppleEvents.h æT Function æD pascal OSErr AEDeleteItem(AEDescList theAEDescList, long index) = {0x303C,0x040E,0xA816}; æDT OSErr myVariable = AEDeleteItem((AEDescList) theAEDescList,() long index); æC æKY AEPutKeyPtr æFc AppleEvents.h æT Function æD pascal OSErr AEPutKeyPtr(AERecord theAERecord, AEKeyword theAEKeyword, DescType typeCode, Ptr dataPtr, Size dataSize) = {0x303C,0x0A0F,0xA816}; æDT OSErr myVariable = AEPutKeyPtr((AERecord) theAERecord,() AEKeyword theAEKeyword,() DescType typeCode,() Ptr dataPtr,() Size dataSize); æC æKY AEPutKeyDesc æFc AppleEvents.h æT Function æD pascal OSErr AEPutKeyDesc(AERecord theAERecord, AEKeyword theAEKeyword, AEDesc theAEDesc) = {0x303C,0x0610,0xA816}; æDT OSErr myVariable = AEPutKeyDesc((AERecord) theAERecord,() AEKeyword theAEKeyword,() AEDesc theAEDesc); æC æKY AEGetKeyPtr æFc AppleEvents.h æT Function æD pascal OSErr AEGetKeyPtr(AERecord theAERecord, AEKeyword theAEKeyword, DescType desiredType, DescType *typeCode, Ptr dataPtr, Size maximumSize, Size *actualSize) = {0x303C,0x0E11,0xA816}; æDT OSErr myVariable = AEGetKeyPtr((AERecord) theAERecord,() AEKeyword theAEKeyword,() DescType desiredType,( DescType) * typeCode,() Ptr dataPtr,() Size maximumSize,( Size) * actualSize); æC æKY AEGetKeyDesc æFc AppleEvents.h æT Function æD pascal OSErr AEGetKeyDesc(AERecord theAERecord, AEKeyword theAEKeyword, DescType desiredType, AEDesc *result) = {0x303C,0x0812,0xA816}; æDT OSErr myVariable = AEGetKeyDesc((AERecord) theAERecord,() AEKeyword theAEKeyword,() DescType desiredType,( AEDesc) * result); æC æKY AESizeOfKeyDesc æFc AppleEvents.h æT Function æD pascal OSErr AESizeOfKeyDesc(AERecord theAERecord, AEKeyword theAEKeyword, DescType *typeCode, Size *dataSize) = {0x303C,0x0829,0xA816}; æDT OSErr myVariable = AESizeOfKeyDesc((AERecord) theAERecord,() AEKeyword theAEKeyword,( DescType) * typeCode,( Size) * dataSize); æC æKY AEDeleteKeyDesc æFc AppleEvents.h æT Function æD pascal OSErr AEDeleteKeyDesc(AERecord theAERecord, AEKeyword theAEKeyword) = {0x303C,0x0413,0xA816}; æDT OSErr myVariable = AEDeleteKeyDesc((AERecord) theAERecord,() AEKeyword theAEKeyword); æC æKY AEPutParamPtr æFc AppleEvents.h æT Function æD pascal OSErr AEPutParamPtr(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType typeCode, Ptr dataPtr, Size dataSize) = {0x303C,0x0A0F,0xA816}; æDT OSErr myVariable = AEPutParamPtr((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType typeCode,() Ptr dataPtr,() Size dataSize); æC æKY AEPutParamDesc æFc AppleEvents.h æT Function æD pascal OSErr AEPutParamDesc(AppleEvent theAppleEvent, AEKeyword theAEKeyword, AEDesc theAEDesc) = {0x303C,0x0610,0xA816}; æDT OSErr myVariable = AEPutParamDesc((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() AEDesc theAEDesc); æC æKY AEGetParamPtr æFc AppleEvents.h æT Function æD pascal OSErr AEGetParamPtr(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType desiredType, DescType *typeCode, Ptr dataPtr, Size maximumSize, Size *actualSize) = {0x303C,0x0E11,0xA816}; æDT OSErr myVariable = AEGetParamPtr((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType desiredType,( DescType) * typeCode,() Ptr dataPtr,() Size maximumSize,( Size) * actualSize); æC æKY AEGetParamDesc æFc AppleEvents.h æT Function æD pascal OSErr AEGetParamDesc(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType desiredType, AEDesc *result) = {0x303C,0x0812,0xA816}; æDT OSErr myVariable = AEGetParamDesc((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType desiredType,( AEDesc) * result); æC æKY AESizeOfParam æFc AppleEvents.h æT Function æD pascal OSErr AESizeOfParam(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType *typeCode, Size *dataSize) = {0x303C,0x0829,0xA816}; æDT OSErr myVariable = AESizeOfParam((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,( DescType) * typeCode,( Size) * dataSize); æC æKY AEDeleteParam æFc AppleEvents.h æT Function æD pascal OSErr AEDeleteParam(AppleEvent theAppleEvent, AEKeyword theAEKeyword) = {0x303C,0x0413,0xA816}; æDT OSErr myVariable = AEDeleteParam((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword); æC æKY AEGetAttributePtr æFc AppleEvents.h æT Function æD pascal OSErr AEGetAttributePtr(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType desiredType, DescType *typeCode, Ptr dataPtr, Size maximumSize, Size *actualSize) = {0x303C,0x0E15,0xA816}; æDT OSErr myVariable = AEGetAttributePtr((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType desiredType,( DescType) * typeCode,() Ptr dataPtr,() Size maximumSize,( Size) * actualSize); æC æKY AEGetAttributeDesc æFc AppleEvents.h æT Function æD pascal OSErr AEGetAttributeDesc(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType desiredType, AEDesc *result) = {0x303C,0x0826,0xA816}; æDT OSErr myVariable = AEGetAttributeDesc((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType desiredType,( AEDesc) * result); æC æKY AESizeOfAttribute æFc AppleEvents.h æT Function æD pascal OSErr AESizeOfAttribute(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType *typeCode, Size *dataSize) = {0x303C,0x0828,0xA816}; æDT OSErr myVariable = AESizeOfAttribute((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,( DescType) * typeCode,( Size) * dataSize); æC æKY AEPutAttributePtr æFc AppleEvents.h æT Function æD pascal OSErr AEPutAttributePtr(AppleEvent theAppleEvent, AEKeyword theAEKeyword, DescType typeCode, Ptr dataPtr, Size dataSize) = {0x303C,0x0A16,0xA816}; æDT OSErr myVariable = AEPutAttributePtr((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() DescType typeCode,() Ptr dataPtr,() Size dataSize); æC æKY AEPutAttributeDesc æFc AppleEvents.h æT Function æD pascal OSErr AEPutAttributeDesc(AppleEvent theAppleEvent, AEKeyword theAEKeyword, AEDesc theAEDesc) = {0x303C,0x0627,0xA816}; æDT OSErr myVariable = AEPutAttributeDesc((AppleEvent) theAppleEvent,() AEKeyword theAEKeyword,() AEDesc theAEDesc); æC æKY AECreateAppleEvent æFc AppleEvents.h æT Function æD pascal OSErr AECreateAppleEvent(AEEventClass theAEEventClass, AEEventID theAEEventID, AEAddressDesc target, short returnID, long transactionID, AppleEvent *result) = {0x303C,0x0B14,0xA816}; æDT OSErr myVariable = AECreateAppleEvent((AEEventClass) theAEEventClass,() AEEventID theAEEventID,() AEAddressDesc target,() short returnID,() long transactionID,( AppleEvent) * result); æC æKY AESend æFc AppleEvents.h æT Function æD pascal OSErr AESend(AppleEvent theAppleEvent, AppleEvent *reply, AESendMode sendMode, AESendPriority sendPriority, long timeOutInTicks, IdleProcPtr idleProc, EventFilterProcPtr filterProc) = {0x303C,0x0D17,0xA816}; æDT OSErr myVariable = AESend((AppleEvent) theAppleEvent,( AppleEvent) * reply,() AESendMode sendMode,() AESendPriority sendPriority,() long timeOutInTicks,() IdleProcPtr idleProc,() EventFilterProcPtr filterProc); æC æKY AEProcessAppleEvent æFc AppleEvents.h æT Function æD pascal OSErr AEProcessAppleEvent(EventRecord theEventRecord) = {0x303C,0x021B,0xA816}; æDT OSErr myVariable = AEProcessAppleEvent((EventRecord) theEventRecord); æC æKY AEResetTimer æFc AppleEvents.h æT Function æD pascal OSErr AEResetTimer(AppleEvent reply) = {0x303C,0x0219,0xA816}; æDT OSErr myVariable = AEResetTimer((AppleEvent) reply); æC æKY AESuspendTheCurrentEvent æFc AppleEvents.h æT Function æD pascal OSErr AESuspendTheCurrentEvent(AppleEvent theAppleEvent) = {0x303C,0x022B,0xA816}; æDT OSErr myVariable = AESuspendTheCurrentEvent((AppleEvent) theAppleEvent); æC æKY AEResumeTheCurrentEvent æFc AppleEvents.h æT Function æD pascal OSErr AEResumeTheCurrentEvent(AppleEvent theAppleEvent, AppleEvent reply, EventHandlerProcPtr dispatcher, long handlerRefcon) = {0x303C,0x0818,0xA816}; æDT OSErr myVariable = AEResumeTheCurrentEvent((AppleEvent) theAppleEvent,() AppleEvent reply,() EventHandlerProcPtr dispatcher,() long handlerRefcon); æC æKY AEGetTheCurrentEvent æFc AppleEvents.h æT Function æD pascal OSErr AEGetTheCurrentEvent(AppleEvent *theAppleEvent) = {0x303C,0x021A,0xA816}; æDT OSErr myVariable = AEGetTheCurrentEvent((AppleEvent *) theAppleEvent); æC æKY AESetTheCurrentEvent æFc AppleEvents.h æT Function æD pascal OSErr AESetTheCurrentEvent(AppleEvent theAppleEvent) = {0x303C,0x022C,0xA816}; æDT OSErr myVariable = AESetTheCurrentEvent((AppleEvent) theAppleEvent); æC æKY AEGetInteractionAllowed æFc AppleEvents.h æT Function æD pascal OSErr AEGetInteractionAllowed(AEInteractAllowed *level) = {0x303C,0x021D,0xA816}; æDT OSErr myVariable = AEGetInteractionAllowed((AEInteractAllowed *) level); æC æKY AESetInteractionAllowed æFc AppleEvents.h æT Function æD pascal OSErr AESetInteractionAllowed(AEInteractAllowed level) = {0x303C,0x011E,0xA816}; æDT OSErr myVariable = AESetInteractionAllowed((AEInteractAllowed) level); æC æKY AEInteractWithUser æFc AppleEvents.h æT Function æD pascal OSErr AEInteractWithUser(long timeOutInTicks, NMRecPtr nmReqPtr, IdleProcPtr idleProc) = {0x303C,0x061C,0xA816}; æDT OSErr myVariable = AEInteractWithUser((long) timeOutInTicks,() NMRecPtr nmReqPtr,() IdleProcPtr idleProc); æC æKY AEInstallEventHandler æFc AppleEvents.h æT Function æD pascal OSErr AEInstallEventHandler(AEEventClass theAEEventClass, AEEventID theAEEventID, EventHandlerProcPtr handler, long handlerRefcon, Boolean isSysHandler) = {0x303C,0x091F,0xA816}; æDT OSErr myVariable = AEInstallEventHandler((AEEventClass) theAEEventClass,() AEEventID theAEEventID,() EventHandlerProcPtr handler,() long handlerRefcon,() Boolean isSysHandler); æC æKY AERemoveEventHandler æFc AppleEvents.h æT Function æD pascal OSErr AERemoveEventHandler(AEEventClass theAEEventClass, AEEventID theAEEventID, EventHandlerProcPtr handler, Boolean isSysHandler) = {0x303C,0x0720,0xA816}; æDT OSErr myVariable = AERemoveEventHandler((AEEventClass) theAEEventClass,() AEEventID theAEEventID,() EventHandlerProcPtr handler,() Boolean isSysHandler); æC æKY AEGetEventHandler æFc AppleEvents.h æT Function æD pascal OSErr AEGetEventHandler(AEEventClass theAEEventClass, AEEventID theAEEventID, EventHandlerProcPtr *handler, long *handlerRefcon, Boolean isSysHandler) = {0x303C,0x0921,0xA816}; æDT OSErr myVariable = AEGetEventHandler((AEEventClass) theAEEventClass,() AEEventID theAEEventID,( EventHandlerProcPtr) * handler,( long) * handlerRefcon,() Boolean isSysHandler); æC æKY AEInstallCoercionHandler æFc AppleEvents.h æT Function æD pascal OSErr AEInstallCoercionHandler(DescType fromType, DescType toType, ProcPtr handler, long handlerRefcon, Boolean fromTypeIsDesc, Boolean isSysHandler) = {0x303C,0x0A22,0xA816}; æDT OSErr myVariable = AEInstallCoercionHandler((DescType) fromType,() DescType toType,() ProcPtr handler,() long handlerRefcon,() Boolean fromTypeIsDesc,() Boolean isSysHandler); æC æKY AERemoveCoercionHandler æFc AppleEvents.h æT Function æD pascal OSErr AERemoveCoercionHandler(DescType fromType, DescType toType, ProcPtr handler, Boolean isSysHandler) = {0x303C,0x0723,0xA816}; æDT OSErr myVariable = AERemoveCoercionHandler((DescType) fromType,() DescType toType,() ProcPtr handler,() Boolean isSysHandler); æC æKY AEGetCoercionHandler æFc AppleEvents.h æT Function æD pascal OSErr AEGetCoercionHandler(DescType fromType, DescType toType, ProcPtr *handler, long *handlerRefcon, Boolean *fromTypeIsDesc, Boolean isSysHandler) = {0x303C,0x0B24,0xA816}; æDT OSErr myVariable = AEGetCoercionHandler((DescType) fromType,() DescType toType,( ProcPtr) * handler,( long) * handlerRefcon,( Boolean) * fromTypeIsDesc,() Boolean isSysHandler); æC æKY AEInstallSpecialHandler æFc AppleEvents.h æT Function æD pascal OSErr AEInstallSpecialHandler(AEKeyword functionClass, ProcPtr handler, Boolean isSysHandler) = {0x303C,0x0500,0xA816}; æDT OSErr myVariable = AEInstallSpecialHandler((AEKeyword) functionClass,() ProcPtr handler,() Boolean isSysHandler); æC æKY AERemoveSpecialHandler æFc AppleEvents.h æT Function æD pascal OSErr AERemoveSpecialHandler(AEKeyword functionClass, ProcPtr handler, Boolean isSysHandler) = {0x303C,0x0501,0xA816}; æDT OSErr myVariable = AERemoveSpecialHandler((AEKeyword) functionClass,() ProcPtr handler,() Boolean isSysHandler); æC æKY AEGetSpecialHandler æFc AppleEvents.h æT Function æD pascal OSErr AEGetSpecialHandler(AEKeyword functionClass, ProcPtr *handler, Boolean isSysHandler) = {0x303C,0x052D,0xA816}; æDT OSErr myVariable = AEGetSpecialHandler((AEKeyword) functionClass,( ProcPtr) * handler,() Boolean isSysHandler); æC æKY AppleTalk.h æKL AFPCommand ASPAbortOS ASPCloseAll ASPCloseSession ASPGetParms ASPGetStatus ASPOpenSession ASPUserCommand ASPUserWrite ATEvent ATPAddRsp ATPCloseSocket ATPGetRequest ATPKillAllGetReq ATPLoad ATPOpenSocket ATPreFlightEvent ATPReqCancel ATPRequest ATPResponse ATPRspCancel ATPSndRequest ATPSndRsp ATPUnload BuildBDS BuildDDPwds BuildLAPwds DDPCloseSocket DDPOpenSocket DDPRdCancel DDPRead DDPWrite GetBridgeAddress GetLocalZones GetMyZone GetNodeAddress GetZoneList IsATPOpen IsMPPOpen LAPAddATQ LAPCloseProtocol LAPOpenProtocol LAPRdCancel LAPRead LAPRmvATQ LAPWrite MPPClose MPPOpen NBPConfirm NBPExtract NBPLoad NBPLookup NBPRegister NBPRemove NBPSetEntity NBPSetNTE NBPUnload OpenXPP PAddResponse PATalkClosePrep PAttachPH PCloseATPSkt PCloseSkt PConfirmName PDetachPH PGetAppleTalkInfo PGetRequest PKillGetReq PKillNBP PKillSendReq PLookupName PNSendRequest POpenATPSkt POpenSkt PRegisterName PRelRspCB PRelTCB PRemoveName PSendRequest PSendResponse PSetSelfSend PWriteDDP PWriteLAP ABByte ABCallType abortOS ABProtoType AddrBlock addResponse afpAddAPPL afpAddCmt afpAddIcon afpByteRangeLock afpCall AFPCommandBlock afpContLogin afpCopyFile afpDelete afpDirClose afpDirCreate afpDTClose afpDTOpen afpEnumerate afpFileCreate afpFlush afpForkClose afpForkFlush afpGetAPPL afpGetCmt afpGetDirParms afpGetFileParms afpGetFlDrParms afpGetForkParms afpGetIcon afpGetSInfo afpGetSParms afpGetVolParms afpGtIcnInfo afpLogin AFPLoginPrm afpLogout afpMapID afpMapName afpMove afpOpenDir afpOpenFork afpOpenVol afpRead afpRename afpRmvAPPL afpRmvCmt afpSetDirParms afpSetFileParms afpSetFlDrParms afpSetForkParms afpSetVolParms afpVolClose afpWrite ASPAbortPrm ASPGetparmsBlk ASPOpenPrm ASPOpenPrmPtr ATalkClosePrep ATalkClosePrepParm ATATPRec ATATPRecHandle ATATPRecPtr ATDDPRec ATDDPRecHandle ATDDPRecPtr ATLAPRec ATLAPRecHandle ATLAPRecPtr ATNBPRec ATNBPRecHandle ATNBPRecPtr ATPaddrBlock ATPaKillQEl ATPatpFlags ATPatpSocket ATPbdsPointer ATPbdsSize ATPbitMap ATPcsCode atpEOMvalue ATPioCompletion ATPioRefNum ATPioResult ATPmisc1 ATPmisc2 ATPnumOfBuffs ATPnumOfResps ATPParamBlock ATPparms ATPPBPtr atpProto atpRefNum ATPreqLength ATPreqPointer ATPreqTID ATPretryCount ATPrspNum atpSendChkvalue atpSize atpSTSvalue atpTIDValidvalue ATPtimeOutVal ATPtransID atpUnitNum ATPuserData atpXOvalue ATQEntry ATQEntryPtr attachPH ATTransCancelClose ATTransClose ATTransClosePrep ATTransOpen BDSElement BDSPtr BDSType BitMapType closeAll closeATPSkt closeSess closeSkt confirmName DDPchecksumFlag DDPlistener DDPparms ddpProto ddpSize DDPsocket DDPwdsPointer detachPH EntityName EntityPtr GetAppleTalkInfoParm GetATalkInfo getParms getRequest getStatus killAllGetReq killGetReq killNBP Killparms killSendReq LAddAEQ LAPAdrBlock LAPhandler LAPMgrCall LAPMgrPtr LAPparms lapProto LAPprotType lapSize LAPwdsPointer lastResident loadNBP lookupName lookupReply LRmvAEQ MOREATPHeader MPPATPHeader MPPcsCode MPPioCompletion MPPioRefNum MPPioResult MPPParamBlock MPPparms MPPPBPtr mppRefNum mppUnitNum NamesTableEntry NBPconfirmAddr NBPcount NBPentityPtr NBPinterval NBPKillparms NBPmaxToGet NBPnewSocket NBPnKillQEl NBPntQElPtr NBPnumGotten NBPparms nbpProto NBPretBuffPtr NBPretBuffSize nbpSize NBPverifyFlag nSendRequest NTElement openATPSkt openSess openSkt registerName relRspCB relTCB removeName RetransType scbMemSize SendReqparms sendRequest sendResponse SetMyZone SetSelfparms setSelfSend tATPAddRsp tATPGetRequest tATPRequest tATPResponse tATPSdRsp tATPSndRequest tDDPRead tDDPWrite tLAPRead tLAPWrite tNBPConfirm tNBPLookup tNBPRegister unloadNBP userCommand userWrite WDSElement writeDDP writeLAP xCall XCallParam xppFlagClr xppFlagSet xppLoadedBit XPPParamBlock XPPParmBlkPtr XPPPBHeader XPPPrmBlk xppRefNum xppUnitNum zipGetLocalZones zipGetMyZone zipGetZoneList æKY mppUnitNum æFc AppleTalk.h æT æD mppUnitNum = 9, /*MPP unit number*/ æC æKY atpUnitNum æFc AppleTalk.h æT æD atpUnitNum = 10, /* ATP unit number */ æC æKY xppUnitNum æFc AppleTalk.h æT æD xppUnitNum = 40, /* XPP unit number */ æC æKY mppRefNum æFc AppleTalk.h æT æD mppRefNum = -10, /*MPP reference number */ æC æKY atpRefNum æFc AppleTalk.h æT æD atpRefNum = -11, /* ATP reference number */ æC æKY xppRefNum æFc AppleTalk.h æT æD xppRefNum = -41, /* XPP reference number */ æC æKY lookupReply æFc AppleTalk.h æT æD lookupReply = 242, /* This command queued to ourself */ æC æKY writeLAP æFc AppleTalk.h æT æD writeLAP = 243, /* Write out LAP packet */ æC æKY detachPH æFc AppleTalk.h æT æD detachPH = 244, /* Detach LAP protocol handler */ æC æKY attachPH æFc AppleTalk.h æT æD attachPH = 245, /* Attach LAP protocol handler */ æC æKY writeDDP æFc AppleTalk.h æT æD writeDDP = 246, /* Write out DDP packet */ æC æKY closeSkt æFc AppleTalk.h æT æD closeSkt = 247, /* Close DDP socket */ æC æKY openSkt æFc AppleTalk.h æT æD openSkt = 248, /* Open DDP socket */ æC æKY loadNBP æFc AppleTalk.h æT æD loadNBP = 249, /* Load NBP command-executing code */ æC æKY lastResident æFc AppleTalk.h æT æD lastResident = 249, /* Last resident command */ æC æKY confirmName æFc AppleTalk.h æT æD confirmName = 250, /* Confirm name */ æC æKY lookupName æFc AppleTalk.h æT æD lookupName = 251, /* Look up name on internet */ æC æKY removeName æFc AppleTalk.h æT æD removeName = 252, /* Remove name from Names Table */ æC æKY registerName æFc AppleTalk.h æT æD registerName = 253, /* Register name in Names Table */ æC æKY killNBP æFc AppleTalk.h æT æD killNBP = 254, /* Kill outstanding NBP request */ æC æKY unloadNBP æFc AppleTalk.h æT æD unloadNBP = 255, /* Unload NBP command code */ æC æKY setSelfSend æFc AppleTalk.h æT æD setSelfSend = 256, /* MPP: Set to allow writes to self */ æC æKY SetMyZone æFc AppleTalk.h æT æD SetMyZone = 257, /* Set my zone name */ æC æKY GetATalkInfo æFc AppleTalk.h æT æD GetATalkInfo = 258, /* get AppleTalk information */ æC æKY ATalkClosePrep æFc AppleTalk.h æT æD ATalkClosePrep = 259, /* AppleTalk close query */ æC æKY nSendRequest æFc AppleTalk.h æT æD nSendRequest = 248, /* NSendRequest code */ æC æKY relRspCB æFc AppleTalk.h æT æD relRspCB = 249, /* Release RspCB */ æC æKY closeATPSkt æFc AppleTalk.h æT æD closeATPSkt = 250, /* Close ATP socket */ æC æKY addResponse æFc AppleTalk.h æT æD addResponse = 251, /* Add response code | Require open skt */ æC æKY sendResponse æFc AppleTalk.h æT æD sendResponse = 252, /* Send response code */ æC æKY getRequest æFc AppleTalk.h æT æD getRequest = 253, /* Get request code */ æC æKY openATPSkt æFc AppleTalk.h æT æD openATPSkt = 254, /* Open ATP socket */ æC æKY sendRequest æFc AppleTalk.h æT æD sendRequest = 255, /* Send request code */ æC æKY relTCB æFc AppleTalk.h æT æD relTCB = 256, /* Release TCB */ æC æKY killGetReq æFc AppleTalk.h æT æD killGetReq = 257, /* Kill GetRequest */ æC æKY killSendReq æFc AppleTalk.h æT æD killSendReq = 258, /* Kill SendRequest */ æC æKY killAllGetReq æFc AppleTalk.h æT æD killAllGetReq = 259, /* Kill all getRequests for a skt */ æC æKY openSess æFc AppleTalk.h æT æD openSess = 255, /* Open session */ æC æKY closeSess æFc AppleTalk.h æT æD closeSess = 254, /* Close session */ æC æKY userCommand æFc AppleTalk.h æT æD userCommand = 253, /* User command */ æC æKY userWrite æFc AppleTalk.h æT æD userWrite = 252, /* User write */ æC æKY getStatus æFc AppleTalk.h æT æD getStatus = 251, /* Get status */ æC æKY afpCall æFc AppleTalk.h æT æD afpCall = 250, /* AFP command (buffer has command code) */ æC æKY getParms æFc AppleTalk.h æT æD getParms = 249, /* Get parameters */ æC æKY abortOS æFc AppleTalk.h æT æD abortOS = 248, /* Abort open session request */ æC æKY closeAll æFc AppleTalk.h æT æD closeAll = 247, /* Close all open sessions */ æC æKY xCall æFc AppleTalk.h æT æD xCall = 246, /* .XPP extended calls */ æC æKY ATTransOpen æFc AppleTalk.h æT æD ATTransOpen = 0, /*AppleTalk has opened*/ æC æKY ATTransClose æFc AppleTalk.h æT æD ATTransClose = 2, /*AppleTalk is about to close*/ æC æKY ATTransClosePrep æFc AppleTalk.h æT æD ATTransClosePrep = 3, /*Is it OK to close AppleTalk ?*/ æC æKY ATTransCancelClose æFc AppleTalk.h æT æD ATTransCancelClose = 4, /*Cancel the ClosePrep transition*/ æC æKY afpByteRangeLock æFc AppleTalk.h æT æD afpByteRangeLock = 1, /*AFPCall command codes*/ æC æKY afpVolClose æFc AppleTalk.h æT æD afpVolClose = 2, /*AFPCall command codes*/ æC æKY afpDirClose æFc AppleTalk.h æT æD afpDirClose = 3, /*AFPCall command codes*/ æC æKY afpForkClose æFc AppleTalk.h æT æD afpForkClose = 4, /*AFPCall command codes*/ æC æKY afpCopyFile æFc AppleTalk.h æT æD afpCopyFile = 5, /*AFPCall command codes*/ æC æKY afpDirCreate æFc AppleTalk.h æT æD afpDirCreate = 6, /*AFPCall command codes*/ æC æKY afpFileCreate æFc AppleTalk.h æT æD afpFileCreate = 7, /*AFPCall command codes*/ æC æKY afpDelete æFc AppleTalk.h æT æD afpDelete = 8, /*AFPCall command codes*/ æC æKY afpEnumerate æFc AppleTalk.h æT æD afpEnumerate = 9, /*AFPCall command codes*/ æC æKY afpFlush æFc AppleTalk.h æT æD afpFlush = 10, /*AFPCall command codes*/ æC æKY afpForkFlush æFc AppleTalk.h æT æD afpForkFlush = 11, /*AFPCall command codes*/ æC æKY afpGetDirParms æFc AppleTalk.h æT æD afpGetDirParms = 12, /*AFPCall command codes*/ æC æKY afpGetFileParms æFc AppleTalk.h æT æD afpGetFileParms = 13, /*AFPCall command codes*/ æC æKY afpGetForkParms æFc AppleTalk.h æT æD afpGetForkParms = 14, /*AFPCall command codes*/ æC æKY afpGetSInfo æFc AppleTalk.h æT æD afpGetSInfo = 15, /*AFPCall command codes*/ æC æKY afpGetSParms æFc AppleTalk.h æT æD afpGetSParms = 16, /*AFPCall command codes*/ æC æKY afpGetVolParms æFc AppleTalk.h æT æD afpGetVolParms = 17, /*AFPCall command codes*/ æC æKY afpLogin æFc AppleTalk.h æT æD afpLogin = 18, /*AFPCall command codes*/ æC æKY afpContLogin æFc AppleTalk.h æT æD afpContLogin = 19, /*AFPCall command codes*/ æC æKY afpLogout æFc AppleTalk.h æT æD afpLogout = 20, /*AFPCall command codes*/ æC æKY afpMapID æFc AppleTalk.h æT æD afpMapID = 21, /*AFPCall command codes*/ æC æKY afpMapName æFc AppleTalk.h æT æD afpMapName = 22, /*AFPCall command codes*/ æC æKY afpMove æFc AppleTalk.h æT æD afpMove = 23, /*AFPCall command codes*/ æC æKY afpOpenVol æFc AppleTalk.h æT æD afpOpenVol = 24, /*AFPCall command codes*/ æC æKY afpOpenDir æFc AppleTalk.h æT æD afpOpenDir = 25, /*AFPCall command codes*/ æC æKY afpOpenFork æFc AppleTalk.h æT æD afpOpenFork = 26, /*AFPCall command codes*/ æC æKY afpRead æFc AppleTalk.h æT æD afpRead = 27, /*AFPCall command codes*/ æC æKY afpRename æFc AppleTalk.h æT æD afpRename = 28, /*AFPCall command codes*/ æC æKY afpSetDirParms æFc AppleTalk.h æT æD afpSetDirParms = 29, /*AFPCall command codes*/ æC æKY afpSetFileParms æFc AppleTalk.h æT æD afpSetFileParms = 30, /*AFPCall command codes*/ æC æKY afpSetForkParms æFc AppleTalk.h æT æD afpSetForkParms = 31, /*AFPCall command codes*/ æC æKY afpSetVolParms æFc AppleTalk.h æT æD afpSetVolParms = 32, /*AFPCall command codes*/ æC æKY afpWrite æFc AppleTalk.h æT æD afpWrite = 33, /*AFPCall command codes*/ æC æKY afpGetFlDrParms æFc AppleTalk.h æT æD afpGetFlDrParms = 34, /*AFPCall command codes*/ æC æKY afpSetFlDrParms æFc AppleTalk.h æT æD afpSetFlDrParms = 35, /*AFPCall command codes*/ æC æKY afpDTOpen æFc AppleTalk.h æT æD afpDTOpen = 48, /*AFPCall command codes*/ æC æKY afpDTClose æFc AppleTalk.h æT æD afpDTClose = 49, /*AFPCall command codes*/ æC æKY afpGetIcon æFc AppleTalk.h æT æD afpGetIcon = 51, /*AFPCall command codes*/ æC æKY afpGtIcnInfo æFc AppleTalk.h æT æD afpGtIcnInfo = 52, /*AFPCall command codes*/ æC æKY afpAddAPPL æFc AppleTalk.h æT æD afpAddAPPL = 53, /*AFPCall command codes*/ æC æKY afpRmvAPPL æFc AppleTalk.h æT æD afpRmvAPPL = 54, /*AFPCall command codes*/ æC æKY afpGetAPPL æFc AppleTalk.h æT æD afpGetAPPL = 55, /*AFPCall command codes*/ æC æKY afpAddCmt æFc AppleTalk.h æT æD afpAddCmt = 56, /*AFPCall command codes*/ æC æKY afpRmvCmt æFc AppleTalk.h æT æD afpRmvCmt = 57, /*AFPCall command codes*/ æC æKY afpGetCmt æFc AppleTalk.h æT æD afpGetCmt = 58, /*AFPCall command codes*/ æC æKY afpAddIcon æFc AppleTalk.h æT æD afpAddIcon = 192, /*Special code for ASP Write commands*/ æC æKY xppLoadedBit æFc AppleTalk.h æT æD xppLoadedBit = 5, /* XPP bit in PortBUse */ æC æKY scbMemSize æFc AppleTalk.h æT æD scbMemSize = 192, /*Size of memory for SCB */ æC æKY xppFlagClr æFc AppleTalk.h æT æD xppFlagClr = 0, /*Cs for AFPCommandBlock */ æC æKY xppFlagSet æFc AppleTalk.h æT æD xppFlagSet = 128, /*StartEndFlag & NewLineFlag fields. */ æC æKY lapSize æFc AppleTalk.h æT æD lapSize = 20, æC æKY ddpSize æFc AppleTalk.h æT æD ddpSize = 26, æC æKY nbpSize æFc AppleTalk.h æT æD nbpSize = 26, æC æKY atpSize æFc AppleTalk.h æT æD atpSize = 56, æC æKY MPPioCompletion æFc AppleTalk.h æT #define æD #define MPPioCompletion MPP.ioCompletion æC æKY MPPioResult æFc AppleTalk.h æT #define æD #define MPPioResult MPP.ioResult æC æKY MPPioRefNum æFc AppleTalk.h æT #define æD #define MPPioRefNum MPP.ioRefNum æC æKY MPPcsCode æFc AppleTalk.h æT #define æD #define MPPcsCode MPP.csCode æC æKY LAPprotType æFc AppleTalk.h æT #define æD #define LAPprotType LAP.protType æC æKY LAPwdsPointer æFc AppleTalk.h æT #define æD #define LAPwdsPointer LAP.LAPptrs.wdsPointer æC æKY LAPhandler æFc AppleTalk.h æT #define æD #define LAPhandler LAP.LAPptrs.handler æC æKY DDPsocket æFc AppleTalk.h æT #define æD #define DDPsocket DDP.socket æC æKY DDPchecksumFlag æFc AppleTalk.h æT #define æD #define DDPchecksumFlag DDP.checksumFlag æC æKY DDPwdsPointer æFc AppleTalk.h æT #define æD #define DDPwdsPointer DDP.DDPptrs.wdsPointer æC æKY DDPlistener æFc AppleTalk.h æT #define æD #define DDPlistener DDP.DDPptrs.listener æC æKY NBPinterval æFc AppleTalk.h æT #define æD #define NBPinterval NBP.interval æC æKY NBPcount æFc AppleTalk.h æT #define æD #define NBPcount NBP.count æC æKY NBPntQElPtr æFc AppleTalk.h æT #define æD #define NBPntQElPtr NBP.NBPPtrs.ntQElPtr æC æKY NBPentityPtr æFc AppleTalk.h æT #define æD #define NBPentityPtr NBP.NBPPtrs.entityPtr æC æKY NBPverifyFlag æFc AppleTalk.h æT #define æD #define NBPverifyFlag NBP.parm.verifyFlag æC æKY NBPretBuffPtr æFc AppleTalk.h æT #define æD #define NBPretBuffPtr NBP.parm.Lookup.retBuffPtr æC æKY NBPretBuffSize æFc AppleTalk.h æT #define æD #define NBPretBuffSize NBP.parm.Lookup.retBuffSize æC æKY NBPmaxToGet æFc AppleTalk.h æT #define æD #define NBPmaxToGet NBP.parm.Lookup.maxToGet æC æKY NBPnumGotten æFc AppleTalk.h æT #define æD #define NBPnumGotten NBP.parm.Lookup.numGotten æC æKY NBPconfirmAddr æFc AppleTalk.h æT #define æD #define NBPconfirmAddr NBP.parm.Confirm.confirmAddr æC æKY NBPnKillQEl æFc AppleTalk.h æT #define æD #define NBPnKillQEl NBPKILL.nKillQEl æC æKY NBPnewSocket æFc AppleTalk.h æT #define æD #define NBPnewSocket NBP.parm.Confirm.newSocket æC æKY ATPioCompletion æFc AppleTalk.h æT #define æD #define ATPioCompletion ATP.ioCompletion æC æKY ATPioResult æFc AppleTalk.h æT #define æD #define ATPioResult ATP.ioResult æC æKY ATPuserData æFc AppleTalk.h æT #define æD #define ATPuserData ATP.userData æC æKY ATPreqTID æFc AppleTalk.h æT #define æD #define ATPreqTID ATP.reqTID æC æKY ATPioRefNum æFc AppleTalk.h æT #define æD #define ATPioRefNum ATP.ioRefNum æC æKY ATPcsCode æFc AppleTalk.h æT #define æD #define ATPcsCode ATP.csCode æC æKY ATPatpSocket æFc AppleTalk.h æT #define æD #define ATPatpSocket ATP.atpSocket æC æKY ATPatpFlags æFc AppleTalk.h æT #define æD #define ATPatpFlags ATP.atpFlags æC æKY ATPaddrBlock æFc AppleTalk.h æT #define æD #define ATPaddrBlock ATP.addrBlock æC æKY ATPreqLength æFc AppleTalk.h æT #define æD #define ATPreqLength ATP.reqLength æC æKY ATPreqPointer æFc AppleTalk.h æT #define æD #define ATPreqPointer ATP.reqPointer æC æKY ATPbdsPointer æFc AppleTalk.h æT #define æD #define ATPbdsPointer ATP.bdsPointer æC æKY ATPtimeOutVal æFc AppleTalk.h æT #define æD #define ATPtimeOutVal SREQ.timeOutVal æC æKY ATPnumOfResps æFc AppleTalk.h æT #define æD #define ATPnumOfResps SREQ.numOfResps æC æKY ATPretryCount æFc AppleTalk.h æT #define æD #define ATPretryCount SREQ.retryCount æC æKY ATPnumOfBuffs æFc AppleTalk.h æT #define æD #define ATPnumOfBuffs OTH1.u0.numOfBuffs æC æKY ATPbitMap æFc AppleTalk.h æT #define æD #define ATPbitMap OTH1.u0.bitMap æC æKY ATPrspNum æFc AppleTalk.h æT #define æD #define ATPrspNum OTH1.u0.rspNum æC æKY ATPbdsSize æFc AppleTalk.h æT #define æD #define ATPbdsSize OTH2.bdsSize æC æKY ATPtransID æFc AppleTalk.h æT #define æD #define ATPtransID OTH2.transID æC æKY ATPaKillQEl æFc AppleTalk.h æT #define æD #define ATPaKillQEl KILL.aKillQEl æC æKY atpXOvalue æFc AppleTalk.h æT æD atpXOvalue = 32, /*ATP exactly-once bit */ æC æKY atpEOMvalue æFc AppleTalk.h æT æD atpEOMvalue = 16, /*ATP End-Of-Message bit */ æC æKY atpSTSvalue æFc AppleTalk.h æT æD atpSTSvalue = 8, /*ATP Send-Transmission-Status bit */ æC æKY atpTIDValidvalue æFc AppleTalk.h æT æD atpTIDValidvalue = 2, /*ATP trans. ID valid bit */ æC æKY atpSendChkvalue æFc AppleTalk.h æT æD atpSendChkvalue = 1, /*ATP send checksum bit */ æC æKY zipGetLocalZones æFc AppleTalk.h æT æD zipGetLocalZones = 5, æC æKY zipGetZoneList æFc AppleTalk.h æT æD zipGetZoneList = 6, æC æKY zipGetMyZone æFc AppleTalk.h æT æD zipGetMyZone = 7, æC æKY LAPMgrPtr æFc AppleTalk.h æT æD LAPMgrPtr = 0xB18, /*Entry point for LAP Manager*/ æC æKY LAPMgrCall æFc AppleTalk.h æT æD LAPMgrCall = 2, /*Offset to LAP routines*/ æC æKY LAddAEQ æFc AppleTalk.h æT æD LAddAEQ = 23, /*LAPAddATQ routine selector*/ æC æKY LRmvAEQ æFc AppleTalk.h æT æD LRmvAEQ = 24, /*LAPRmvATQ routine selector*/ æC æKY ABCallType tLAPRead tLAPWrite tDDPRead tDDPWrite tNBPLookup tNBPConfirm tNBPRegister tATPSndRequest tATPGetRequest tATPSdRsp tATPAddRsp tATPRequest tATPResponse æFc AppleTalk.h æT enum æD enum {tLAPRead,tLAPWrite,tDDPRead,tDDPWrite,tNBPLookup,tNBPConfirm,tNBPRegister, tATPSndRequest,tATPGetRequest,tATPSdRsp,tATPAddRsp,tATPRequest,tATPResponse}; typedef unsigned char ABCallType; æC æKY ABProtoType lapProto ddpProto nbpProto atpProto æFc AppleTalk.h æT enum æD enum {lapProto,ddpProto,nbpProto,atpProto}; typedef unsigned char ABProtoType; æC æKY ABByte æFc AppleTalk.h æT typedef æD typedef Byte ABByte; æC æKY LAPAdrBlock æFc AppleTalk.h æT struct æD struct LAPAdrBlock { unsigned char dstNodeID; unsigned char srcNodeID; ABByte lapProtType; }; typedef struct LAPAdrBlock LAPAdrBlock; æC æKY ATQEntry ATQEntryPtr æFc AppleTalk.h æT struct æD struct ATQEntry { struct ATQEntry *qLink; /*next queue entry*/ short qType; /*queue type*/ ProcPtr CallAddr; /*pointer to your routine*/ }; typedef struct ATQEntry ATQEntry; typedef ATQEntry *ATQEntryPtr; æC æKY AddrBlock æFc AppleTalk.h æT struct æD struct AddrBlock { short aNet; unsigned char aNode; unsigned char aSocket; }; typedef struct AddrBlock AddrBlock; æC æKY EntityName EntityPtr æFc AppleTalk.h æT struct æD struct EntityName { Str32 objStr; char pad1; /*Str32's aligned on even word boundries.*/ Str32 typeStr; char pad2; Str32 zoneStr; char pad3; }; typedef struct EntityName EntityName; typedef EntityName *EntityPtr; æC \* Real definition of EntityName is 3 PACKED strings of any length (32 is just an example). No offsets for Asm since each String address must be calculated by adding length byte to last string ptr. In Pascal, String(32) will be 34 bytes long since fields never start on an odd byte unless they are only a byte long. So this will generate correct looking interfaces for Pascal and C, but they will not be the same, which is OK since they are not used. */ æKY RetransType æFc AppleTalk.h æT struct æD struct RetransType { unsigned char retransInterval; unsigned char retransCount; }; typedef struct RetransType RetransType; æC æKY BDSElement æFc AppleTalk.h æT struct æD struct BDSElement { short buffSize; Ptr buffPtr; short dataSize; long userBytes; }; typedef struct BDSElement BDSElement; æC æKY BDSType æFc AppleTalk.h æT typedef æD typedef BDSElement BDSType[8]; æC æKY BDSPtr æFc AppleTalk.h æT typedef æD typedef BDSType *BDSPtr; æC æKY BitMapType æFc AppleTalk.h æT typedef æD typedef char BitMapType; æC æKY ATLAPRec ATLAPRecPtr ATLAPRecHandle æFc AppleTalk.h æT struct æD struct ATLAPRec { ABCallType abOpcode; short abResult; long abUserReference; LAPAdrBlock lapAddress; short lapReqCount; short lapActCount; Ptr lapDataPtr; }; typedef struct ATLAPRec ATLAPRec; typedef ATLAPRec *ATLAPRecPtr, **ATLAPRecHandle; æC æKY ATDDPRec ATDDPRecPtr ATDDPRecHandle æFc AppleTalk.h æT struct æD struct ATDDPRec { ABCallType abOpcode; short abResult; long abUserReference; short ddpType; short ddpSocket; AddrBlock ddpAddress; short ddpReqCount; short ddpActCount; Ptr ddpDataPtr; short ddpNodeID; }; typedef struct ATDDPRec ATDDPRec; typedef ATDDPRec *ATDDPRecPtr, **ATDDPRecHandle; æC æKY ATNBPRec ATNBPRecPtr ATNBPRecHandle æFc AppleTalk.h æT struct æD struct ATNBPRec { ABCallType abOpcode; short abResult; long abUserReference; EntityPtr nbpEntityPtr; Ptr nbpBufPtr; short nbpBufSize; short nbpDataField; AddrBlock nbpAddress; RetransType nbpRetransmitInfo; }; typedef struct ATNBPRec ATNBPRec; typedef ATNBPRec *ATNBPRecPtr, **ATNBPRecHandle; æC æKY ATATPRec ATATPRecPtr ATATPRecHandle æFc AppleTalk.h æT struct æD struct ATATPRec { ABCallType abOpcode; short abResult; long abUserReference; short atpSocket; AddrBlock atpAddress; short atpReqCount; Ptr atpDataPtr; BDSPtr atpRspBDSPtr; BitMapType atpBitMap; short atpTransID; short atpActCount; long atpUserData; Boolean atpXO; Boolean atpEOM; short atpTimeOut; short atpRetries; short atpNumBufs; short atpNumRsp; short atpBDSSize; long atpRspUData; Ptr atpRspBuf; short atpRspSize; }; typedef struct ATATPRec ATATPRec; typedef ATATPRec *ATATPRecPtr, **ATATPRecHandle; æC æKY AFPCommandBlock æFc AppleTalk.h æT struct æD typedef struct { char cmdByte; char startEndFlag; short forkRefNum; long rwOffset; long reqCount; char newLineFlag; char newLineChar; }AFPCommandBlock; æC æKY XPPPBHeader æFc AppleTalk.h æT struct æD #define XPPPBHeader \ QElem *qLink;\ short qType;\ short ioTrap;\ Ptr ioCmdAddr;\ ProcPtr ioCompletion;\ OSErr ioResult;\ long cmdResult;\ short ioVRefNum;\ short ioRefNum;\ short csCode; æC æKY XPPPrmBlk æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader short sessRefnum; /*Offset to session refnum*/ char aspTimeout; /*Timeout for ATP*/ char aspRetry; /*Retry count for ATP*/ short cbSize; /*Command block size*/ Ptr cbPtr; /*Command block pointer*/ short rbSize; /*Reply buffer size*/ Ptr rbPtr; /*Reply buffer pointer*/ short wdSize; /*Write Data size*/ Ptr wdPtr; /*Write Data pointer*/ char ccbStart[296]; /*CCB memory allocated for driver afpWrite max size(CCB)=296 all other calls=150*/ }XPPPrmBlk; æC æKY AFPLoginPrm æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader short sessRefnum; /*Offset to session refnum */ char aspTimeout; /*Timeout for ATP */ char aspRetry; /*Retry count for ATP */ short cbSize; /*Command block size */ Ptr cbPtr; /*Command block pointer */ short rbSize; /*Reply buffer size */ Ptr rbPtr; /*Reply buffer pointer */ AddrBlock afpAddrBlock; /*block in AFP login */ Ptr afpSCBPtr; /*SCB pointer in AFP login */ Ptr afpAttnRoutine; /*routine pointer in AFP login */ char ccbFill[144]; /*CCB memory allocated for driver Login needs only 150 bytes BUT CCB really starts in the middle of AFPSCBPtr and also clobbers AFPAttnRoutine. */ }AFPLoginPrm; æC æKY ASPOpenPrm ASPOpenPrmPtr æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader short sessRefnum; /*Offset to session refnum */ char aspTimeout; /*Timeout for ATP */ char aspRetry; /*Retry count for ATP */ AddrBlock serverAddr; /*Server address block */ Ptr scbPointer; /*SCB pointer */ Ptr attnRoutine; /*Attention routine pointer*/ }ASPOpenPrm; typedef ASPOpenPrm *ASPOpenPrmPtr; æC æKY ASPAbortPrm æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader Ptr abortSCBPtr; /*SCB pointer for AbortOS */ }ASPAbortPrm; æC æKY ASPGetparmsBlk æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader short aspMaxCmdSize; /*For SPGetParms*/ short aspQuantumSize; short numSesss; }ASPGetparmsBlk; æC æKY XCallParam æFc AppleTalk.h æT struct æD typedef struct { XPPPBHeader short xppSubCode; char xppTimeout; /*retry interval (seconds)*/ char xppRetry; /*retry count*/ short filler1; Ptr zipBuffPtr; /*pointer to buffer (must be 578 bytes)*/ short zipNumZones; /*no. of zone names in this response*/ char zipLastFlag; /*non-zero if no more zones*/ char filler2; /*filler*/ char zipInfoField[70]; /*on initial call, set first word to zero*/ }XCallParam; æC æKY WDSElement æFc AppleTalk.h æT struct æD typedef struct { short entryLength; Ptr entryPtr; }WDSElement; æC æKY NTElement æFc AppleTalk.h æT struct æD typedef struct { AddrBlock nteAddress; /*network address of entity*/ char filler; char entityData[99]; /*Object, Type & Zone*/ }NTElement; æC æKY NamesTableEntry æFc AppleTalk.h æT struct æD typedef struct { Ptr qNext; /*ptr to next NTE*/ NTElement nt; }NamesTableEntry; æC æKY MPPATPHeader æFc AppleTalk.h æT struct æD #define MPPATPHeader \ QElem *qLink; /*next queue entry*/\ short qType; /*queue type*/\ short ioTrap; /*routine trap*/\ Ptr ioCmdAddr; /*routine address*/\ ProcPtr ioCompletion; /*completion routine*/\ OSErr ioResult; /*result code*/\ long userData; /*Command result (ATP user bytes)*/\ short reqTID; /*request transaction ID*/\ short ioRefNum; /*driver reference number*/\ short csCode; /*Call command code*/ æC æKY MPPparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader }MPPparms; æC æKY LAPparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader char protType; /*ALAP protocol Type */ char filler; union { Ptr wdsPointer; /*-> write data structure*/ Ptr handler; /*-> protocol handler routine*/ } LAPptrs; }LAPparms; æC æKY DDPparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader char socket; /*socket number */ char checksumFlag; /*check sum flag */ union { Ptr wdsPointer; /*-> write data structure*/ Ptr listener; /*->write data structure or -> Listener*/ } DDPptrs; }DDPparms; æC æKY NBPparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader char interval; /*retry interval */ char count; /*retry count */ union { Ptr ntQElPtr; Ptr entityPtr; } NBPPtrs; union { char verifyFlag; struct { Ptr retBuffPtr; short retBuffSize; short maxToGet; short numGotten; } Lookup; struct { AddrBlock confirmAddr; char newSocket; } Confirm; } parm; }NBPparms; æC æKY SetSelfparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader char newSelfFlag; /*self-send toggle flag */ char oldSelfFlag; /*previous self-send state */ }SetSelfparms; æC æKY NBPKillparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader Ptr nKillQEl; /*ptr to i/o queue element to cancel */ }NBPKillparms; æC æKY GetAppleTalkInfoParm æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader /*max. concurrent NBP requests*/ short version; /*requested info version*/ Ptr varsPtr; /*pointer to well known MPP vars*/ Ptr DCEPtr; /*pointer to MPP DCE*/ short portID; /*port number [0..7]*/ long configuration; /*32-bit configuration word*/ short selfSend; /*non zero if SelfSend enabled*/ short netLo; /*low value of network range*/ short netHi; /*high value of network range*/ long ourAdd; /*our 24-bit AppleTalk address*/ long routerAddr; /*24-bit address of (last) router*/ short numOfPHs; /*max. number of protocol handlers*/ short numOfSkts; /*max. number of static sockets*/ short numNBPEs; /*max. concurrent NBP requests*/ Ptr nTQueue; /*pointer to registered name queue*/ short LAlength; /*length in bytes of data link addr*/ Ptr linkAddr; /*data link address returned*/ Ptr zoneName; /*zone name returned*/ }GetAppleTalkInfoParm; æC æKY ATalkClosePrepParm æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader Ptr appName; /*pointer to application name in buffer*/ }ATalkClosePrepParm; æC æKY MPPParamBlock MPPPBPtr æFc AppleTalk.h æT struct æD typedef union { MPPparms MPP; /*General MPP parms*/ LAPparms LAP; /*ALAP calls*/ DDPparms DDP; /*DDP calls*/ NBPparms NBP; /*NBP calls*/ SetSelfparms SETSELF ; NBPKillparms NBPKILL ; GetAppleTalkInfoParm GAIINFO; ATalkClosePrepParm ATALKCLOSE; }MPPParamBlock; typedef MPPParamBlock *MPPPBPtr; æC æKY MOREATPHeader æFc AppleTalk.h æT struct æD #define MOREATPHeader \ char atpSocket; /*currbitmap for requests or ATP socket number*/\ char atpFlags; /*control information*/\ AddrBlock addrBlock; /*source/dest. socket address*/\ short reqLength; /*request/response length*/\ Ptr reqPointer; /*->request/response Data*/\ Ptr bdsPointer; /*->response BDS */ æC æKY ATPparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader MOREATPHeader }ATPparms; æC æKY SendReqparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader MOREATPHeader char filler; /*numOfBuffs */ char timeOutVal; /*timeout interval */ char numOfResps; /*number of responses actually received */ char retryCount; /*number of retries */ short intBuff; /*used internally for NSendRequest */ char TRelTime; }SendReqparms; æC æKY ATPmisc1 æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader MOREATPHeader union { char bitMap; /*bitmap received */ char numOfBuffs; /*number of responses being sent*/ char rspNum; /*sequence number*/ } u0; }ATPmisc1; æC æKY ATPmisc2 æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader MOREATPHeader char filler; char bdsSize; /*number of BDS elements */ short transID; /*transaction ID recd. */ }ATPmisc2; æC æKY Killparms æFc AppleTalk.h æT struct æD typedef struct { MPPATPHeader MOREATPHeader Ptr aKillQEl; /*ptr to i/o queue element to cancel*/ }Killparms; æC æKY ATPParamBlock ATPPBPtr æFc AppleTalk.h æT struct æD typedef union { ATPparms ATP; /*General ATP parms*/ SendReqparms SREQ; /*sendrequest parms*/ ATPmisc1 OTH1; /*and a few others*/ ATPmisc2 OTH2; /*and a few others*/ Killparms KILL; /*and a few others */ }ATPParamBlock; typedef ATPParamBlock *ATPPBPtr; æC æKY XPPParamBlock XPPParmBlkPtr æFc AppleTalk.h æT struct æD typedef union { XPPPrmBlk XPP; ASPGetparmsBlk GETPARM; ASPAbortPrm ABORT; ASPOpenPrm OPEN; AFPLoginPrm LOGIN; XCallParam XCALL; }XPPParamBlock; typedef XPPParamBlock *XPPParmBlkPtr; æC æKY OpenXPP æFc AppleTalk.h æT Function æD pascal OSErr OpenXPP(short *xppRefnum); æDT OSErr myVariable = OpenXPP((short *) xppRefnum); æRI æRI æC »Opening the .XPP Driver To open the .XPP driver, issue a Device Manager Open call. (Refer to the Device Manager chapter.) The name of the .XPP driver is '.XPP'. The original Macintosh ROMs require that .XPP be opened only once. With new ROMs, the .XPP unit number can always be obtained through an Open call. With old ROMs only, the .XPP unit number must be hard coded to XPPUnitNum (40) since only one Open call can be issued to the driver. The .XPP driver cannot be opened unless AppleTalk is open. The application must ensure that the .MPP and .ATP drivers are opened, as described earlier in this chapter. The xppLoaded bit (bit 5) in the PortBUse byte in low memory indicates whether or not the .XPP driver is open. »Example The following is an example of the procedure an application might use to open the .XPP driver. ; Routine: OpenXPP ; ; Open the .XPP driver and return the driver refNum for it. ; ; Exit: D0 = error code (ccr's set) ; D1 = XPP driver refNum (if no errors) ; ; All other registers preserved ; xppUnitNum EQU 40 ;default XPP driver number xppTfRNum EQU -(xppUnitNum+1) ;default XPP driver refNum OpenXPP MOVE.L A0-A1/D2,-(SP) ;save registers MOVE ROM85,D0 ;check ROM type byte BPL.S @10 ;branch if >=128K ROMs BTST #xppLoadedBit,PortBUse ;is the XPP driver open already? BEQ.S @10 ;if not open, then branch to Open code MOVE #xppTfRNum,D1 ;else use this as driver refnum MOVEQ #0,D0 ;set noErr BRA.S @90 ;and exit ; ; XPP driver not open. Make an _Open call to it. If using a 128K ; ROM machine and the driver is already open, we will make another ; Open call to it just so we get the correct driver refNum. ; @10 SUB #ioQElSize,SP ;allocate temporary param block MOVE.L SP,A0 ;A0 -> param block LEA XPPName, A1 ;A1 -> XPP (ASP/AFP) driver name MOVE.L A1,ioFileName(A0) ;driver name into param block CLR.B ioPermssn(A0) ;clear permissions byte _Open MOVE ioRefNum(A0),D1 ;D1=driver refNum (invalid if error) ADD #ioQElSize,SP ;deallocate temp param block @90 MOVE.L (SP)+,A0-A1/D2 ;restore registers TST D0 ;error? (set ccr's) RTS XPPName DC.B 4 ;length of string DC.B '.XPP' ;driver name From Pascal, XPP can be opened through the OpenXPP call, which returns the driver’s reference number: FUNCTION OpenXPP (VAR xppRefnum: INTEGER) : OSErr; »Open Errors Errors returned when calling the Device Manager Open routine if the function does not execute properly include the following: • errors returned by System • portInUse is returned if the AppleTalk port is in use by a driver other than AppleTalk or if AppleTalk is not open. »Closing the .XPP Driver To close the .XPP driver, call the Device Manager Close routine. Warning: There is generally no reason to close the driver. Use this call sparingly, if at all. This call should generally be used only by system-level applications. »Close Errors Errors returned when calling the Device Manager Close routine if the function does not execute properly include the following: • errors returned by System • closeErr (new ROMs only) is returned if you try to close the driver and there are sessions active through that driver. When sessions are active, closeErr is returned and the driver remains open. • on old ROMs the driver is closed whether or not sessions are active and no error is returned. Results are unpredictable if sessions are still active. »Session Control Block The session control block (SCB) is a nonrelocatable block of data passed by the caller to XPP upon session opening. XPP reserves this block for use in maintaining an open session. The SCB size is defined by the constant scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. This block can be reused once a CloseSess call is issued and completed for that session or when the session is indicated as closed. æKY ASPOpenSession æFc AppleTalk.h æT Function æD pascal OSErr ASPOpenSession(ASPOpenPrmPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPOpenSession((ASPOpenPrmPtr) thePBptr,(Boolean) async); æRI V-536 æC »AppleTalk Session Protocol Functions This section contains descriptions of the .XPP driver functions that you can call. Each function description shows the required parameter block fields, their offsets within the parameter block and a brief definition of the field. Possible result codes are also described. »Note on Result Codes An important distinction exists between the aspParamErr and aspSessClose result codes that may be returned by the .XPP driver. When the driver returns aspParamErr to a call that takes as an input a session reference number, the session reference number does not relate to a valid open session. There could be several reasons for this, such as the workstation or server end closed the session or the server end of the session died. The aspSessClosed result code indicates that even though the session reference number relates to a valid session, that particular session is in the process of closing down (although the session is not yet closed). FUNCTION ASPOpenSession (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always ASPOpenSess --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 serverAddr long word Server socket address --> 36 scbPointer pointer Pointer to session control block --> 40 attnRoutine pointer Pointer to attention routine ASPOpenSession initiates (opens) a session between the workstation and a server. The required parameter block is shown above. A brief definition of the fields follows. SessRefnum is a unique number identifying the open session between the workstation and the server. The SessRefnum is returned when the function completes successfully and is used in all calls to identify the session. ASPTimeOut is the interval in seconds between retries of the open session request. ASPRetry is the number of retries that will be attempted. ServerAddr is the network identifier or address of the socket on which the server is listening. SCBPointer points to a nonrelocatable block of data for the session control block (SCB) that the .XPP driver reserves for use in maintaining an open session. The SCB size is defined by the constant scbMemSize. The SCB is a locked block and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. This block can be reused when a CloseSess call is issued and completed for that session, or when the session is indicated as closed through return of aspParamErr as the result of a call for that session. AttnRoutine is a pointer to a routine that is invoked if an attention from the server is received, or upon session closing. If this pointer is equal to zero, no attention routine will be invoked. Result codes aspNoMoreSess Driver cannot support another session aspParamErr Server returned bad (positive) error code aspNoServers No servers at that address, or the server did not respond to the request reqAborted OpenSess was aborted by an AbortOS aspBadVersNum Server cannot support the offered version number aspServerBusy Server cannot open another session Note: The number of sessions that the driver is capable of supporting depends on the machine that the driver is running on. æKY ASPCloseSession æFc AppleTalk.h æT Function æD pascal OSErr ASPCloseSession(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPCloseSession((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-537 æC Parameter block --> 26 csCode word Always ASPCloseSession --> 28 sessRefnum word Session reference number ASPCloseSession closes the session identified by the sessRefnum returned in the ASPOpenSession call. ASPCloseSession aborts any calls that are active on the session, closes the session, and calls the attention routine, if any, with an attention code of zero (zero is invalid as a real attention code). Result codes aspParamErr Parameter error, indicates an invalid session reference number aspSessClosed Session already in process of closing æKY ASPAbortOS æFc AppleTalk.h æT Function æD pascal OSErr ASPAbortOS(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPAbortOS((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-537 æC Parameter block --> 26 csCode word Always ASPAbortOS --> 28 abortSCBPointer pointer Pointer to session control block ASPAbortOS aborts a pending (not yet completed) ASPOpenSession call. The aborted ASPOpenSession call will return a reqAborted error. AbortSCBPointer points to the original SCB used in the the pending ASPOpenSession call. Result codes cbNotFound SCB not found, no outstanding open session to be aborted. Pointer did not point to an open session SCB. æKY ASPGetParms æFc AppleTalk.h æT Function æD pascal OSErr ASPGetParms(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPGetParms((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-538 æC Parameter block --> 26 csCode word Always ASPGetParms --> 28 aspMaxCmdSize word Maximum size of command block --> 30 aspQuantumSize word Maximum data size --> 32 numSesss word Number of sessions ASPGetParms returns three ASP parameters. This call does not require an open session. ASPMaxCmdSize is the maximum size of a command that can be sent to the server. ASPQuantumSize is the maximum size of data that can be transferred to the server in a Write request or from the server in a command reply. NumSess is the number of concurrent sessions supported by the driver. æKY ASPCloseAll æFc AppleTalk.h æT Function æD pascal OSErr ASPCloseAll(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPCloseAll((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-538 æC Parameter block --> 26 csCode word Always ASPCloseAll ASPCloseAll closes every session that the driver has active, aborting all active requests and invoking the attention routines where provided. This call should be used carefully. ASPCloseAll can be used as a system level resource for making sure all sessions are closed prior to closing the driver. æKY ASPUserWrite æFc AppleTalk.h æT Function æD pascal OSErr ASPUserWrite(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPUserWrite((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-538 æC Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always UserWrite --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command block size --> 34 cbPtr pointer Command block pointer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB ASPUserWrite transfers data on a session. ASPUserWrite is one of the two main calls that can be used to transfer data on an ASP session. The other call that performs a similar data transfer is ASPUserCommand described below. The ASPUserWrite command returns data in two different places. Four bytes of data are returned in the cmdResult field and a variable size reply buffer is also returned. CmdResult is four bytes of data returned by the server. SessRefnum is the session reference number returned in the ASPOpenSession call. ASPTimeOut is the interval in seconds between retries of the call. Notice that there is no aspRetry field (retries are infinite). The command will be retried at the prescribed interval until completion or the session is closed. CBSize is the size in bytes of the command data that is to be written on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. Note that this buffer is not the data to be written by the command but only the data of the command itself. CBPtr points to the command data. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is passed and indicates the size of the write data in bytes to be sent by the command. WDSize is also returned and indicates the size of the write data that was actually written. WDPointer points to the write data buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement, refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number, session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer; the buffer will be filled, data will be truncated æKY ASPUserCommand æFc AppleTalk.h æT Function æD pascal OSErr ASPUserCommand(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPUserCommand((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-539 æC Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always ASPUserCommand --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command block size --> 34 cbPtr pointer Command block pointer <-> 38 rbSize word Reply buffer and reply size --> 40 rbPtr pointer Reply buffer pointer --> 50 ccbStart record Start of memory for CCB ASPUserCommand is used to send a command to the server on a session. SessRefnum is the session reference number returned in the ASPOpenSession call. ASPTimeOut is the interval in seconds between retries of the call. Notice that there is no aspRetry field (retries are infinite). The command will be retried at the prescribed interval until completion or the session is closed. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPointer points to the block of data containing the command that is to be sent to the server on the session. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number, session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer; the buffer will be filled, data will be truncated æKY ASPGetStatus æFc AppleTalk.h æT Function æD pascal OSErr ASPGetStatus(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = ASPGetStatus((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-540 æC Parameter block --> 26 csCode word Always ASPGetStatus --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 serverAddr long word Server socket address <-> 38 rbSize word Reply buffer and reply size --> 40 rbPtr pointer Reply buffer pointer --> 50 ccbStart record Start of memory for CCB ASPGetStatus returns server status. This call is also used as GetServerInfo at the AFP level. This call is unique in that it transfers data over the network without having a session open. This call does not pass any data but requests that server status be returned. ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. ServerAddr is the network identifier or address of the socket on which the server is listening. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspBufTooSmall Reply is bigger than response buffer, or Replysize is bigger than ReplyBuffsize aspNoServer No response from server at address used in call æKY AFPCommand æFc AppleTalk.h æT Function æD pascal OSErr AFPCommand(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = AFPCommand((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-542 æC »AFPCall Function The AFPCall function can have one of the following command formats. • General • Login • AFPWrite • AFPRead »General Command Format FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB The general command format for the AFPCall function passes an AFP command to the server. This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite. Note that from Pascal this call is referred to as AFPCommand. CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call by the driver. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to start of the block of data (command block) containing the command that is to be sent to the server on the session. The first byte of the command block must contain the AFP command byte. Subsequent bytes in the command buffer contain the parameters associated with the command as defined in the AFP document. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is the size of data to be written to the server (only used if the command is one that is mapped to an ASPUserWrite). WDPtr points to the write data buffer (only used if the command is one that is mapped to an ASPUserWrite). CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number; session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated afpParmError AFP command block size is equal to zero. This error will also be returned if the command byte in the command block is equal to 0 or $FF (255) or GetSrvrStatus (15). »Login Command Format The AFP login command executes a series of AFP operations as defined in the AFP Draft Proposal. For further information, refer to the AFP document. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 afpAddrBlock long word Server address block <-> 48 afpSCBPtr pointer SCB pointer <-> 52 afpAttnRoutine pointer Attention routine pointer --> 50 ccbStart record Start of command control block CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number (returned by the AFPLogin call). ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to the block of data (command block) containing the AFP login command that is to be sent to the server on the session. The first byte of the command block must be the AFP login command byte. Subsequent bytes in the command buffer contain the parameters associated with the command. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. AFPServerAddr is the network identifier or address of the socket on which the server is listening. AFPSCBPointer points to a locked block of data for the session control block (SCB). The SCB size is defined by scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the server is received. When afpAttnRoutine is equal to zero, no attention routine will be invoked. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Note: In the parameter block, the afpSCBPointer and the afpAttnRoutine fields overlap with the start of the CCB and are modified by the call. Result codes aspSizeErr Command block size is bigger than MaxCmdSize aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated aspNoServer Server not responding aspServerBusy Server cannot open another session aspBadVersNum Server cannot support the offered ASP version number aspNoMoreSess Driver cannot support another session. »AFPWrite Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 wdSize word (used internally) <-> 46 wdPtr pointer Write data pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the aspGetParms call. CBPtr points to the block of data (see command block structure below) containing the AFP write command that is to be sent to the server on the session. The first byte of the Command Block must contain the AFP write command byte. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is used internally. Note: This command does not pass the write data size in the queue element but in the command buffer. XPP will look for the size in that buffer. WDPtr is a pointer to the block of data to be written. Note that this field will be updated by XPP as it proceeds and will always point to that section of the data which XPP is currently writing. CCBStart is the start of the memory to be used by the XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Command Block Structure: The AFP write command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPtr. --> 0 cmdByte byte AFP call command byte --> 1 startEndFlag byte Start/end Flag <-> 4 rwOffset long word Offset within fork to write <-> 8 reqCount long word Requested count CmdByte is the AFP call command byte and must contain the AFP write command code. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the rwOffset field is relative to the beginning or the end of the fork (all other bits are zero). 0 = relative to the beginning of the fork 1 = relative to the end of the fork RWOffset is the byte offset within the fork at which the write is to begin. ReqCount indicates the size of the data to be written and is returned as the actual size written. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will always indicate the current value of these fields. The Pascal structure of the AFP command buffer follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; {unused by write} newLineChar: CHAR; {unused by write} END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer »AFPRead Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer --> 38 rbSize word Used internally <-> 40 rbPtr pointer Reply buffer pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the GetParms call. CBPtr points to the block of data (command block) containing the AFP read command that is to be sent to the server on the session. The first byte of the command block must contain the AFP read command byte. The command block structure is shown below. RBSize is used internally. Note: This command does not pass the read size in the queue element but in the command buffer. XPP will look for the size in that buffer. RBPtr points to the reply buffer. Note that this field will be updated by XPP as it proceeds and will always point to that section of the buffer that XPP is currently reading into. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to The CCB Sizes section later in this chapter. Command Block Structure: The AFP read command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPointer. --> 0 cmdByte byte AFP call command byte <-> 4 rwOffset long word Offset within fork to read <-> 8 reqCount long word Requested count --> 12 newLineFlag byte Newline Flag --> 13 newLineChar byte Newline Character CmdByte is the AFP call command byte and must contain the AFP read command code. RWOffset is the byte offset within the fork at which the read is to begin. ReqCount indicates the size of the read data buffer and is returned as the actual size read. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will always indicate the current value of these fields. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not the read is to terminate at a specified character (all other bits are zero). 0 = no Newline Character is specified 1 = a Newline Character is specified NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in reading the fork, causes the read operation to terminate. The Pascal structure of the AFPCommand follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; {unused for read} forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer æKY GetLocalZones æFc AppleTalk.h æT Function æD pascal OSErr GetLocalZones(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = GetLocalZones((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-542 æC »AFPCall Function The AFPCall function can have one of the following command formats. • General • Login • AFPWrite • AFPRead »General Command Format FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB The general command format for the AFPCall function passes an AFP command to the server. This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite. Note that from Pascal this call is referred to as AFPCommand. CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call by the driver. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to start of the block of data (command block) containing the command that is to be sent to the server on the session. The first byte of the command block must contain the AFP command byte. Subsequent bytes in the command buffer contain the parameters associated with the command as defined in the AFP document. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is the size of data to be written to the server (only used if the command is one that is mapped to an ASPUserWrite). WDPtr points to the write data buffer (only used if the command is one that is mapped to an ASPUserWrite). CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number; session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated afpParmError AFP command block size is equal to zero. This error will also be returned if the command byte in the command block is equal to 0 or $FF (255) or GetSrvrStatus (15). »Login Command Format The AFP login command executes a series of AFP operations as defined in the AFP Draft Proposal. For further information, refer to the AFP document. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 afpAddrBlock long word Server address block <-> 48 afpSCBPtr pointer SCB pointer <-> 52 afpAttnRoutine pointer Attention routine pointer --> 50 ccbStart record Start of command control block CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number (returned by the AFPLogin call). ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to the block of data (command block) containing the AFP login command that is to be sent to the server on the session. The first byte of the command block must be the AFP login command byte. Subsequent bytes in the command buffer contain the parameters associated with the command. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. AFPServerAddr is the network identifier or address of the socket on which the server is listening. AFPSCBPointer points to a locked block of data for the session control block (SCB). The SCB size is defined by scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the server is received. When afpAttnRoutine is equal to zero, no attention routine will be invoked. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Note: In the parameter block, the afpSCBPointer and the afpAttnRoutine fields overlap with the start of the CCB and are modified by the call. Result codes aspSizeErr Command block size is bigger than MaxCmdSize aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated aspNoServer Server not responding aspServerBusy Server cannot open another session aspBadVersNum Server cannot support the offered ASP version number aspNoMoreSess Driver cannot support another session. »AFPWrite Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 wdSize word (used internally) <-> 46 wdPtr pointer Write data pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the aspGetParms call. CBPtr points to the block of data (see command block structure below) containing the AFP write command that is to be sent to the server on the session. The first byte of the Command Block must contain the AFP write command byte. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is used internally. Note: This command does not pass the write data size in the queue element but in the command buffer. XPP will look for the size in that buffer. WDPtr is a pointer to the block of data to be written. Note that this field will be updated by XPP as it proceeds and will always point to that section of the data which XPP is currently writing. CCBStart is the start of the memory to be used by the XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Command Block Structure: The AFP write command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPtr. --> 0 cmdByte byte AFP call command byte --> 1 startEndFlag byte Start/end Flag <-> 4 rwOffset long word Offset within fork to write <-> 8 reqCount long word Requested count CmdByte is the AFP call command byte and must contain the AFP write command code. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the rwOffset field is relative to the beginning or the end of the fork (all other bits are zero). 0 = relative to the beginning of the fork 1 = relative to the end of the fork RWOffset is the byte offset within the fork at which the write is to begin. ReqCount indicates the size of the data to be written and is returned as the actual size written. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will always indicate the current value of these fields. The Pascal structure of the AFP command buffer follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; {unused by write} newLineChar: CHAR; {unused by write} END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer »AFPRead Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer --> 38 rbSize word Used internally <-> 40 rbPtr pointer Reply buffer pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the GetParms call. CBPtr points to the block of data (command block) containing the AFP read command that is to be sent to the server on the session. The first byte of the command block must contain the AFP read command byte. The command block structure is shown below. RBSize is used internally. Note: This command does not pass the read size in the queue element but in the command buffer. XPP will look for the size in that buffer. RBPtr points to the reply buffer. Note that this field will be updated by XPP as it proceeds and will always point to that section of the buffer that XPP is currently reading into. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to The CCB Sizes section later in this chapter. Command Block Structure: The AFP read command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPointer. --> 0 cmdByte byte AFP call command byte <-> 4 rwOffset long word Offset within fork to read <-> 8 reqCount long word Requested count --> 12 newLineFlag byte Newline Flag --> 13 newLineChar byte Newline Character CmdByte is the AFP call command byte and must contain the AFP read command code. RWOffset is the byte offset within the fork at which the read is to begin. ReqCount indicates the size of the read data buffer and is returned as the actual size read. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will always indicate the current value of these fields. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not the read is to terminate at a specified character (all other bits are zero). 0 = no Newline Character is specified 1 = a Newline Character is specified NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in reading the fork, causes the read operation to terminate. The Pascal structure of the AFPCommand follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; {unused for read} forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer æKY GetZoneList æFc AppleTalk.h æT Function æD pascal OSErr GetZoneList(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = GetZoneList((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-542 æC »AFPCall Function The AFPCall function can have one of the following command formats. • General • Login • AFPWrite • AFPRead »General Command Format FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB The general command format for the AFPCall function passes an AFP command to the server. This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite. Note that from Pascal this call is referred to as AFPCommand. CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call by the driver. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to start of the block of data (command block) containing the command that is to be sent to the server on the session. The first byte of the command block must contain the AFP command byte. Subsequent bytes in the command buffer contain the parameters associated with the command as defined in the AFP document. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is the size of data to be written to the server (only used if the command is one that is mapped to an ASPUserWrite). WDPtr points to the write data buffer (only used if the command is one that is mapped to an ASPUserWrite). CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number; session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated afpParmError AFP command block size is equal to zero. This error will also be returned if the command byte in the command block is equal to 0 or $FF (255) or GetSrvrStatus (15). »Login Command Format The AFP login command executes a series of AFP operations as defined in the AFP Draft Proposal. For further information, refer to the AFP document. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 afpAddrBlock long word Server address block <-> 48 afpSCBPtr pointer SCB pointer <-> 52 afpAttnRoutine pointer Attention routine pointer --> 50 ccbStart record Start of command control block CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number (returned by the AFPLogin call). ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to the block of data (command block) containing the AFP login command that is to be sent to the server on the session. The first byte of the command block must be the AFP login command byte. Subsequent bytes in the command buffer contain the parameters associated with the command. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. AFPServerAddr is the network identifier or address of the socket on which the server is listening. AFPSCBPointer points to a locked block of data for the session control block (SCB). The SCB size is defined by scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the server is received. When afpAttnRoutine is equal to zero, no attention routine will be invoked. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Note: In the parameter block, the afpSCBPointer and the afpAttnRoutine fields overlap with the start of the CCB and are modified by the call. Result codes aspSizeErr Command block size is bigger than MaxCmdSize aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated aspNoServer Server not responding aspServerBusy Server cannot open another session aspBadVersNum Server cannot support the offered ASP version number aspNoMoreSess Driver cannot support another session. »AFPWrite Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 wdSize word (used internally) <-> 46 wdPtr pointer Write data pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the aspGetParms call. CBPtr points to the block of data (see command block structure below) containing the AFP write command that is to be sent to the server on the session. The first byte of the Command Block must contain the AFP write command byte. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is used internally. Note: This command does not pass the write data size in the queue element but in the command buffer. XPP will look for the size in that buffer. WDPtr is a pointer to the block of data to be written. Note that this field will be updated by XPP as it proceeds and will always point to that section of the data which XPP is currently writing. CCBStart is the start of the memory to be used by the XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Command Block Structure: The AFP write command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPtr. --> 0 cmdByte byte AFP call command byte --> 1 startEndFlag byte Start/end Flag <-> 4 rwOffset long word Offset within fork to write <-> 8 reqCount long word Requested count CmdByte is the AFP call command byte and must contain the AFP write command code. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the rwOffset field is relative to the beginning or the end of the fork (all other bits are zero). 0 = relative to the beginning of the fork 1 = relative to the end of the fork RWOffset is the byte offset within the fork at which the write is to begin. ReqCount indicates the size of the data to be written and is returned as the actual size written. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will always indicate the current value of these fields. The Pascal structure of the AFP command buffer follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; {unused by write} newLineChar: CHAR; {unused by write} END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer »AFPRead Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer --> 38 rbSize word Used internally <-> 40 rbPtr pointer Reply buffer pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the GetParms call. CBPtr points to the block of data (command block) containing the AFP read command that is to be sent to the server on the session. The first byte of the command block must contain the AFP read command byte. The command block structure is shown below. RBSize is used internally. Note: This command does not pass the read size in the queue element but in the command buffer. XPP will look for the size in that buffer. RBPtr points to the reply buffer. Note that this field will be updated by XPP as it proceeds and will always point to that section of the buffer that XPP is currently reading into. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to The CCB Sizes section later in this chapter. Command Block Structure: The AFP read command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPointer. --> 0 cmdByte byte AFP call command byte <-> 4 rwOffset long word Offset within fork to read <-> 8 reqCount long word Requested count --> 12 newLineFlag byte Newline Flag --> 13 newLineChar byte Newline Character CmdByte is the AFP call command byte and must contain the AFP read command code. RWOffset is the byte offset within the fork at which the read is to begin. ReqCount indicates the size of the read data buffer and is returned as the actual size read. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will always indicate the current value of these fields. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not the read is to terminate at a specified character (all other bits are zero). 0 = no Newline Character is specified 1 = a Newline Character is specified NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in reading the fork, causes the read operation to terminate. The Pascal structure of the AFPCommand follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; {unused for read} forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer æKY GetMyZone æFc AppleTalk.h æT Function æD pascal OSErr GetMyZone(XPPParmBlkPtr thePBptr,Boolean async); æDT OSErr myVariable = GetMyZone((XPPParmBlkPtr) thePBptr,(Boolean) async); æRI V-542 æC »AFPCall Function The AFPCall function can have one of the following command formats. • General • Login • AFPWrite • AFPRead »General Command Format FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB The general command format for the AFPCall function passes an AFP command to the server. This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite. Note that from Pascal this call is referred to as AFPCommand. CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call by the driver. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to start of the block of data (command block) containing the command that is to be sent to the server on the session. The first byte of the command block must contain the AFP command byte. Subsequent bytes in the command buffer contain the parameters associated with the command as defined in the AFP document. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is the size of data to be written to the server (only used if the command is one that is mapped to an ASPUserWrite). WDPtr points to the write data buffer (only used if the command is one that is mapped to an ASPUserWrite). CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number; session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated afpParmError AFP command block size is equal to zero. This error will also be returned if the command byte in the command block is equal to 0 or $FF (255) or GetSrvrStatus (15). »Login Command Format The AFP login command executes a series of AFP operations as defined in the AFP Draft Proposal. For further information, refer to the AFP document. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 afpAddrBlock long word Server address block <-> 48 afpSCBPtr pointer SCB pointer <-> 52 afpAttnRoutine pointer Attention routine pointer --> 50 ccbStart record Start of command control block CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number (returned by the AFPLogin call). ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to the block of data (command block) containing the AFP login command that is to be sent to the server on the session. The first byte of the command block must be the AFP login command byte. Subsequent bytes in the command buffer contain the parameters associated with the command. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. AFPServerAddr is the network identifier or address of the socket on which the server is listening. AFPSCBPointer points to a locked block of data for the session control block (SCB). The SCB size is defined by scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the server is received. When afpAttnRoutine is equal to zero, no attention routine will be invoked. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Note: In the parameter block, the afpSCBPointer and the afpAttnRoutine fields overlap with the start of the CCB and are modified by the call. Result codes aspSizeErr Command block size is bigger than MaxCmdSize aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated aspNoServer Server not responding aspServerBusy Server cannot open another session aspBadVersNum Server cannot support the offered ASP version number aspNoMoreSess Driver cannot support another session. »AFPWrite Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 wdSize word (used internally) <-> 46 wdPtr pointer Write data pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the aspGetParms call. CBPtr points to the block of data (see command block structure below) containing the AFP write command that is to be sent to the server on the session. The first byte of the Command Block must contain the AFP write command byte. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is used internally. Note: This command does not pass the write data size in the queue element but in the command buffer. XPP will look for the size in that buffer. WDPtr is a pointer to the block of data to be written. Note that this field will be updated by XPP as it proceeds and will always point to that section of the data which XPP is currently writing. CCBStart is the start of the memory to be used by the XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Command Block Structure: The AFP write command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPtr. --> 0 cmdByte byte AFP call command byte --> 1 startEndFlag byte Start/end Flag <-> 4 rwOffset long word Offset within fork to write <-> 8 reqCount long word Requested count CmdByte is the AFP call command byte and must contain the AFP write command code. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the rwOffset field is relative to the beginning or the end of the fork (all other bits are zero). 0 = relative to the beginning of the fork 1 = relative to the end of the fork RWOffset is the byte offset within the fork at which the write is to begin. ReqCount indicates the size of the data to be written and is returned as the actual size written. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will always indicate the current value of these fields. The Pascal structure of the AFP command buffer follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; {unused by write} newLineChar: CHAR; {unused by write} END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer »AFPRead Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer --> 38 rbSize word Used internally <-> 40 rbPtr pointer Reply buffer pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the GetParms call. CBPtr points to the block of data (command block) containing the AFP read command that is to be sent to the server on the session. The first byte of the command block must contain the AFP read command byte. The command block structure is shown below. RBSize is used internally. Note: This command does not pass the read size in the queue element but in the command buffer. XPP will look for the size in that buffer. RBPtr points to the reply buffer. Note that this field will be updated by XPP as it proceeds and will always point to that section of the buffer that XPP is currently reading into. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to The CCB Sizes section later in this chapter. Command Block Structure: The AFP read command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPointer. --> 0 cmdByte byte AFP call command byte <-> 4 rwOffset long word Offset within fork to read <-> 8 reqCount long word Requested count --> 12 newLineFlag byte Newline Flag --> 13 newLineChar byte Newline Character CmdByte is the AFP call command byte and must contain the AFP read command code. RWOffset is the byte offset within the fork at which the read is to begin. ReqCount indicates the size of the read data buffer and is returned as the actual size read. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will always indicate the current value of these fields. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not the read is to terminate at a specified character (all other bits are zero). 0 = no Newline Character is specified 1 = a Newline Character is specified NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in reading the fork, causes the read operation to terminate. The Pascal structure of the AFPCommand follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; {unused for read} forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer æKY PAttachPH æFc AppleTalk.h æT Function æD pascal OSErr PAttachPH(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PAttachPH((MPPPBPtr) thePBptr,(Boolean) async); æRI II-308, V-513 æC AttachPH function Parameter block -> 26 csCode word ;always attachPH -> 28 protType byte ;ALAP protocol type -> 30 handler pointer ;protocol handler AttachPH adds the protocol handler pointed to by handler to the node's protocol table. ProtType specifies what kind of frame the protocol handler can service. After AttachPH is called, the protocol handler is called for each incoming frame whose ALAP protocol type equals protType. Result codes noErr No error lapProtErr Error attaching protocol type æKY PDetachPH æFc AppleTalk.h æT Function æD pascal OSErr PDetachPH(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PDetachPH((MPPPBPtr) thePBptr,(Boolean) async); æRI II-308, V-513 æC DetachPH function Parameter block -> 26 csCode word ;always detachPH -> 28 protType byte ;ALAP protocol type DetachPH removes from the node's protocol table the specified ALAP protocol type and corresponding protocol handler. Result codes noErr No error lapProtErr Error detaching protocol type æKY PWriteLAP æFc AppleTalk.h æT Function æD pascal OSErr PWriteLAP(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PWriteLAP((MPPPBPtr) thePBptr,(Boolean) async); æRI II-307, V-513 æC WriteLAP function Parameter block -> 26 csCode word ;always writeLAP -> 30 wdsPointer pointer ;write data structure WriteLAP sends a frame to another node. The frame data and destination of the frame are described by the write data structure pointed to by wdsPointer. The first two data bytes of an ALAP frame sent to another computer using the AppleTalk Manager must indicate the length of the frame in bytes. The ALAP protocol type byte must be in the range 1 to 127. Result codes noErr No error excessCollsns No CTS received after 32 RTS's ddpLengthErr Packet length exceeds maximum lapProtErr Invalid ALAP protocol type æKY POpenSkt æFc AppleTalk.h æT Function æD pascal OSErr POpenSkt(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = POpenSkt((MPPPBPtr) thePBptr,(Boolean) async); æRI II-311, V-513 æC OpenSkt function Parameter block -> 26 csCode word ;always openSkt <-> 28 socket byte ;socket number -> 30 listener pointer ;socket listener OpenSkt adds a socket and its socket listener to the socket table. If the socket parameter is nonzero, it must be in the range 64 to 127, and it specifies the socket's number; if socket is 0, OpenSkt opens a socket with a socket number in the range 128 to 254, and returns it in the socket parameter. Listener contains a pointer to the socket listener. OpenSkt will return ddpSktErr if you pass the number of an already opened socket, if you pass a socket number greater than 127, or if the socket table is full (the socket table can hold a maximum of 12 sockets). Result codes noErr No error ddpSktErr Socket error æKY PCloseSkt æFc AppleTalk.h æT Function æD pascal OSErr PCloseSkt(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PCloseSkt((MPPPBPtr) thePBptr,(Boolean) async); æRI II-312,V513 æC CloseSkt function Parameter block -> 26 csCode word ;always closeSkt -> 28 socket byte ;socket number CloseSkt removes the entry of the specified socket from the socket table. If you pass a socket number of 0, or if you attempt to close a socket that isn't open, CloseSkt will return ddpSktErr. Result codes noErr No error ddpSktErr Socket error æKY PWriteDDP æFc AppleTalk.h æT Function æD pascal OSErr PWriteDDP(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PWriteDDP((MPPPBPtr) thePBptr,(Boolean) async); æRI II-312,V-513 æC WriteDDP function Parameter block -> 26 csCode word ;always writeDDP -> 28 socket byte ;socket number -> 29 checksumFlag byte ;checksum flag -> 30 wdsPointer pointer ;write data structure WriteDDP sends a datagram to another socket. WDSPointer points to a write data structure containing the datagram and the address of the destination socket. If checksumFlag is TRUE, WriteDDP will compute the checksum for all datagrams requiring long headers. Result codes noErr No error ddpLenErr Datagram length too big ddpSktErr Socket error noBridgeErr No bridge found æKY PRegisterName æFc AppleTalk.h æT Function æD pascal OSErr PRegisterName(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PRegisterName((MPPPBPtr) thePBptr,(Boolean) async); æRI II-322,V-513 æC RegisterName function Parameter block -> 26 csCode word ;always registerName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 ntQElPtr pointer ;names table element pointer -> 34 verifyFlag byte ;set if verify needed RegisterName adds the name and address of an entity to the node's names table. NTQElPtr points to a names table entry containing the entity's name and internet address (in the form shown in Figure 13 above). Meta-characters aren't allowed in the object and type fields of the entity name; the zone field, however, must contain the meta-character "*". If verifyFlag is TRUE, RegisterName checks on the network to see if the name is already in use, and returns a result code of nbpDuplicate if so. Interval and count contain the retry interval in eight-tick units and the retry count. When a retry is made, the count field is modified. Warning: The names table entry passed to RegisterName remains the property of NBP until removed from the names table. Don't attempt to remove or modify it. If you've allocated memory using a NewHandle call, you must lock it as long as the name is registered. Warning: VerifyFlag should normally be set before calling RegisterName. Result codes noErr No error nbpDuplicate Duplicate name already exists nbpNISErr Error opening names information socket æKY PLookupName æFc AppleTalk.h æT Function æD pascal OSErr PLookupName(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PLookupName((MPPPBPtr) thePBptr,(Boolean) async); æRI II-323,V-513 æC LookupName function Parameter block -> 26 csCode word ;always lookupName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 entityPtr pointer ;pointer to entity name -> 34 retBuffPtr pointer ;pointer to buffer -> 38 retBuffSize word ;buffer size in bytes -> 40 maxToGet word ;matches to get <-> 42 numGotten word ;matches found LookupName returns the addresses of all entities with a specified name. EntityPtr points to the entity's name (in the form shown in Figure 13 above). Meta- characters are allowed in the entity name. RetBuffPtr and retBuffSize contain the location and size of an area of memory in which the tuples describing the entity names and their corresponding addresses should be returned. MaxToGet indicates the maximum number of matching names to find addresses for; the actual number of addresses found is returned in numGotten. Interval and count contain the retry interval and the retry count. LookupName completes when either the number of matches is equal to or greater than maxToGet, or the retry count has been exceeded. The count field is decremented for each retransmission. Note: NumGotten is first set to 0 and then incremented with each match found. You can test the value in this field, and can start examining the received addresses in the buffer while the lookup continues. Result codes noErr No error nbpBuffOvr Buffer overflow æKY PConfirmName æFc AppleTalk.h æT Function æD pascal OSErr PConfirmName(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PConfirmName((MPPPBPtr) thePBptr,(Boolean) async); æRI II-323,V-513 æC ConfirmName function Parameter block -> 26 csCode word ;always confirmName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 entityPtr pointer ;pointer to entity name -> 34 confirmAddr pointer ;entity address <- 38 newSocket byte ;socket number ConfirmName confirms that an entity known by name and address still exists (is still entered in the names directory). EntityPtr points to the entity's name (in the form shown in Figure 13 above). ConfirmAddr specifies the address to confirmed. No meta-characters are allowed in the entity name. Interval and count contain the retry interval and the retry count. The socket number of the entity is returned in newSocket. ConfirmName is more efficient than LookupName in terms of network traffic. Result codes noErr No error nbpConfDiff Name confirmed for different socket nbpNoConfirm Name not confirmed æKY PRemoveName æFc AppleTalk.h æT Function æD pascal OSErr PRemoveName(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PRemoveName((MPPPBPtr) thePBptr,(Boolean) async); æRI II-324,V-513 æC RemoveName function Parameter block -> 26 csCode word ;always removeName -> 30 entityPtr pointer ;pointer to entity name RemoveName removes an entity name from the names table of the given entity's node. Result codes noErr No error nbpNotFound Name not found æKY PSetSelfSend æFc AppleTalk.h æT Function æD pascal OSErr PSetSelfSend(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PSetSelfSend((MPPPBPtr) thePBptr,(Boolean) async); æRI V-516 æC _______________________________________________________________________________ »SENDING PACKETS TO ONE’S OWN NODE _______________________________________________________________________________ Upon opening, the ability to send a packet to one’s own node (intranode delivery) is disabled. This feature of the AppleTalk Manager can be manipulated through the SetSelfSend function. Once enabled, it is possible, at all levels, to send packets to entities within one’s own node. An example of where this might be desirable is an application sending data to a print spooler that is actually running in the background on the same node. Enabling (or disabling) this feature affects the entire node and should be performed with care. For instance, a desk accessory may not expect to receive names from within its own node as a response to an NBP look-up; enabling this feature from an application could break the desk accessory. All future programs should be written with this feature in mind. FUNCTION PSetSelfSend (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr; Parameter Block --> 26 csCode word Always PSetSelfSend --> 28 newSelfFlag byte New SelfSend flag <-- 29 oldSelfFlag byte Old SelfSend flag PSetSelfSend enables or disables the intranode delivery feature of the AppleTalk Manager. If newSelfFlag is nonzero, the feature will be enabled; otherwise it will be disabled. The previous value of the flag will be returned in oldSelfFlag. Result Codes noErr No error æKY PKillNBP æFc AppleTalk.h æT Function æD pascal OSErr PKillNBP(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PKillNBP((MPPPBPtr) thePBptr,(Boolean) async); æRI V-518 æC _______________________________________________________________________________ »NAME BINDING PROTOCOL CHANGES _______________________________________________________________________________ Changes to the Name Binding Protocol include supporting multiple concurrent requests and a means for aborting an active request. »Multiple Concurrent NBP Requests NBP now supports multiple concurrent active requests. Specifically, a number of LookupNames, RegisterNames and ConfirmNames can all be active concurrently. The maximum number of concurrent requests is machine dependent; if it is exceeded the error tooManyReqs will be returned. Active requests can be aborted by the PKillNBP call. »KillNBP function FUNCTION PKillNBP (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; •••Refer to Technical Note #199:••• Parameter block --> 26 csCode word Always PKillNBP --> 28 aKillQEl pointer Pointer to queue element PKillNBP is used to abort an outstanding LookupName, RegisterName or ConfirmName request. To abort one of these calls, place a pointer to the queue element of the call to abort in a KillQEl and issue the PKillNBP call. The call will be completed with a ReqAborted error. Result Codes noErr No error cbNotFound aKillQEl does not point to a valid NBP queue element æKY PGetAppleTalkInfo æFc AppleTalk.h æT Function æD pascal OSErr PGetAppleTalkInfo(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PGetAppleTalkInfo((MPPPBPtr) thePBptr,(Boolean) async); æRI V-518 æC _______________________________________________________________________________ »NAME BINDING PROTOCOL CHANGES _______________________________________________________________________________ Changes to the Name Binding Protocol include supporting multiple concurrent requests and a means for aborting an active request. »Multiple Concurrent NBP Requests NBP now supports multiple concurrent active requests. Specifically, a number of LookupNames, RegisterNames and ConfirmNames can all be active concurrently. The maximum number of concurrent requests is machine dependent; if it is exceeded the error tooManyReqs will be returned. Active requests can be aborted by the PKillNBP call. »KillNBP function FUNCTION PKillNBP (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; •••Refer to Technical Note #199:••• Parameter block --> 26 csCode word Always PKillNBP --> 28 aKillQEl pointer Pointer to queue element PKillNBP is used to abort an outstanding LookupName, RegisterName or ConfirmName request. To abort one of these calls, place a pointer to the queue element of the call to abort in a KillQEl and issue the PKillNBP call. The call will be completed with a ReqAborted error. Result Codes noErr No error cbNotFound aKillQEl does not point to a valid NBP queue element æKY PATalkClosePrep æFc AppleTalk.h æT Function æD pascal OSErr PATalkClosePrep(MPPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = PATalkClosePrep((MPPPBPtr) thePBptr,(Boolean) async); æRI V-518 æC _______________________________________________________________________________ »NAME BINDING PROTOCOL CHANGES _______________________________________________________________________________ Changes to the Name Binding Protocol include supporting multiple concurrent requests and a means for aborting an active request. »Multiple Concurrent NBP Requests NBP now supports multiple concurrent active requests. Specifically, a number of LookupNames, RegisterNames and ConfirmNames can all be active concurrently. The maximum number of concurrent requests is machine dependent; if it is exceeded the error tooManyReqs will be returned. Active requests can be aborted by the PKillNBP call. »KillNBP function FUNCTION PKillNBP (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; •••Refer to Technical Note #199:••• Parameter block --> 26 csCode word Always PKillNBP --> 28 aKillQEl pointer Pointer to queue element PKillNBP is used to abort an outstanding LookupName, RegisterName or ConfirmName request. To abort one of these calls, place a pointer to the queue element of the call to abort in a KillQEl and issue the PKillNBP call. The call will be completed with a ReqAborted error. Result Codes noErr No error cbNotFound aKillQEl does not point to a valid NBP queue element æKY POpenATPSkt æFc AppleTalk.h æT Function æD pascal OSErr POpenATPSkt(ATPPBPtr thePBptr,Boolean async); æDT OSErr myVariable = POpenATPSkt((ATPPBPtr) thePBptr,(Boolean) async); æRI II-315,V-513 æC OpenATPSkt function Parameter block -> 26 csCode word ;always openATPSkt <-> 28 atpSocket byte ;socket number -> 30 addrBlock long word ;socket request specification OpenATPSkt opens a socket for the purpose of receiving requests. ATPSocket contains the socket number of the socket to open. If it's 0, a number is dynamically assigned and returned in atpSocket. AddrBlock contains a specification of the socket addresses from which requests will be accepted. A 0 in the network number, node ID, or socket number field of addrBlock means that requests will be accepted from every network, node, or socket, respectively. Result codes noErr No error tooManySkts Too many responding sockets noDataArea Too many outstanding ATP calls æKY PCloseATPSkt æFc AppleTalk.h æT Function æD pascal OSErr PCloseATPSkt(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PCloseATPSkt((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-316,V-513 æC CloseATPSkt function Parameter block -> 26 csCode word ;always closeATPSkt -> 28 atpSocket byte ;socket number CloseATPSkt closes the socket whose number is specified by atpSocket, for the purpose of receiving requests. Result codes noErr No error æKY PSendRequest æFc AppleTalk.h æT Function æD pascal OSErr PSendRequest(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PSendRequest((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-316,V-513 æC SendRequest function Parameter block -> 18 userData long word ;user bytes <- 22 reqTID word ;transaction ID used in request -> 26 csCode word ;always sendRequest <- 28 currBitMap byte ;bit map <-> 29 atpFlags byte ;control information -> 30 addrBlock long word ;destination socket address -> 34 reqLength word ;request size in bytes -> 36 reqPointer pointer ;pointer to request data -> 40 bdsPointer pointer ;pointer to response BDS -> 44 numOfBuffs byte ;number of responses expected -> 45 timeOutVal byte ;timeout interval <- 46 numOfResps byte ;number of responses received <-> 47 retryCount byte ;number of retries SendRequest sends a request to another socket and waits for a response. UserData contains the four user bytes. AddrBlock indicates the socket to which the request should be sent. ReqLength and reqPointer contain the size and location of the request to send. BDSPointer points to a response BDS where the responses are to be returned; numOfBuffs indicates the number of responses requested. The number of responses received is returned in numOfResps. If a nonzero value is returned in numOfResps, you can examine currBitMap to determine which packets of the transaction were actually received and to detect pieces for higher-level recovery, if desired. TimeOutVal indicates the number of seconds that SendRequest should wait for a response before resending the request. RetryCount indicates the maximum number of retries SendRequest should attempt. The end-of-message flag of atpFlags will be set if the EOM bit is set in the last packet received in a valid response sequence. The exactly-once flag should be set if you want the request to be part of an exactly-once transaction. To cancel a SendRequest call, you need the transaction ID; it's returned in reqTID. You can examine reqTID before the completion of the call, but its contents are valid only after the tidValid bit of atpFlags has been set. SendRequest completes when either an entire response is received or the retry count is exceeded. Note: The value provided in retryCount will be modified during SendRequest if any retries are made. This field is used to monitor the number of retries; for each retry, it's decremented by 1. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls reqAborted Request canceled by user æKY PGetRequest æFc AppleTalk.h æT Function æD pascal OSErr PGetRequest(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PGetRequest((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-317,V-513 æC GetRequest function Parameter block <- 18 userData long word ;user bytes -> 26 csCode word ;always getRequest -> 28 atpSocket byte ;socket number <- 29 atpFlags byte ;control information <- 30 addrBlock long word ;source of request <-> 34 reqLength word ;request buffer size -> 36 reqPointer pointer ;pointer to request buffer <- 44 bitMap byte ;bit map <- 46 transID word ;transaction ID GetRequest sets up the mechanism to receive a request sent by a SendRequest call. UserData returns the four user bytes from the request. ATPSocket contains the socket number of the socket that should listen for a request. The internet address of the socket from which the request was sent is returned in addrBlock. ReqLength and reqPointer indicate the size (in bytes) and location of a buffer to store the incoming request. The actual size of the request is returned in reqLength. The transaction bit map and transaction ID will be returned in bitMap and transID. The exactly-once flag in atpFlags will be set if the request is part of an exactly-once transaction. GetRequest completes when a request is received. Result codes noErr No error badATPSkt Bad responding socket æKY PSendResponse æFc AppleTalk.h æT Function æD pascal OSErr PSendResponse(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PSendResponse((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-317,V-513 æC SendResponse function Parameter block <- 18 userData long word ;user bytes from TRel <- 22 reqTID word ;transaction ID used in request -> 26 csCode word ;always sendResponse -> 28 atpSocket byte ;socket number -> 29 atpFlags byte ;control information -> 30 addrBlock long word ;response destination -> 40 bdsPointer pointer ;pointer to response BDS -> 44 numOfBuffs byte ;number of response packets being sent -> 45 bdsSize byte ;BDS size in elements -> 46 transID word ;transaction ID SendResponse sends a response to a socket. If the response was part of an exactly- once transaction, userData will contain the user bytes from the TRel packet. ATPSocket contains the socket number from which the response should be sent. The end-of-message flag in atpFlags should be set if the response contains the final packet in a transaction composed of a group of packets and the number of responses is less than requested. AddrBlock indicates the address of the socket to which the response should be sent. BDSPointer points to a response BDS containing room for the maximum number of responses to be sent; bdsSize contains this maximum number. NumOfBuffs contains the number of response packets to be sent in this call; you may wish to make AddResponse calls to complete the response. TransID indicates the transaction ID of the associated request. During exactly-once transactions, SendResponse doesn't complete until either a TRel packet is received from the socket that made the request, or the retry count is exceeded. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received noDataArea Too many outstanding ATP calls badBuffNum Sequence number out of range æKY PAddResponse æFc AppleTalk.h æT Function æD pascal OSErr PAddResponse(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PAddResponse((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-318,V-513 æC AddResponse function Parameter block -> 18 userData long word ;user bytes -> 26 csCode word ;always addResponse -> 28 atpSocket byte ;socket number -> 29 atpFlags byte ;control information -> 30 addrBlock long word ;response destination -> 34 reqLength word ;response size -> 36 reqPointer pointer ;pointer to response -> 44 rspNum byte ;sequence number -> 46 transID word ;transaction ID AddResponse sends an additional response packet to a socket that has already been sent the initial part of a response via SendResponse. UserData contains the four user bytes. ATPSocket contains the socket number from which the response should be sent. The end-of-message flag in atpFlags should be set if this response packet is the final packet in a transaction composed of a group of packets and the number of responses is less than requested. AddrBlock indicates the socket to which the response should be sent. ReqLength and reqPointer contain the size (in bytes) and location of the response to send; rspNum indicates the sequence number of the response (in the range 0 to 7). TransID must contain the transaction ID. Warning: If the transaction is part of an exactly-once transaction, the buffer used in the AddResponse call must not be altered or released until the corresponding SendResponse call has completed. Result codes noErr No error badATPSkt Bad responding socket noSendResp AddResponse issued before SendResponse badBuffNum Sequence number out of range noDataArea Too many outstanding ATP calls æKY PRelTCB æFc AppleTalk.h æT Function æD pascal OSErr PRelTCB(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PRelTCB((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-319,V-513 æC RelTCB function Parameter block -> 26 csCode word ;always relTCB -> 30 addrBlock long word ;destination of request -> 46 transID word ;transaction ID of request RelTCB dequeues the specified SendRequest call and returns the result code reqAborted for the aborted call. The transaction ID can be obtained from the reqTID field of the SendRequest queue entry; see the description of SendRequest for details. Result codes noErr No error cbNotFound ATP control block not found noDataArea Too many outstanding ATP calls æKY PRelRspCB æFc AppleTalk.h æT Function æD pascal OSErr PRelRspCB(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PRelRspCB((ATPPBPtr) thePBPtr,(Boolean) async); æRI II-319,V-514 æC RelRspCB function Parameter block -> 26 csCode word ;always relRspCB -> 28 atpSocket byte ;socket number that request was received on -> 30 addrBlock long word ;source of request -> 46 transID word ;transaction ID of request In an exactly-once transaction, RelRspCB cancels the specified SendResponse, without waiting for the release timer to expire or a TRel packet to be received. No error is returned for the SendResponse call. Whan called to cancel a transaction that isn't using exactly-once service, RelRspCB returns cbNotFound. The transaction ID can be obtained from the reqTID field of the SendResponse queue entry; see the description of SendResponse for details. Result codes noErr No error cbNotFound ATP control block not found æKY PNSendRequest æFc AppleTalk.h æT Function æD pascal OSErr PNSendRequest(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PNSendRequest((ATPPBPtr) thePBPtr,(Boolean) async); æRI V-516 æC »Sending an ATP Request Through a Specified Socket ATP requests can now be sent through client-specified sockets. ATP previously would open a dynamic socket, send the request through it, and close the socket when the request was completed. The client can now choose to send a request through an already-opened socket; this also allows more than one request to be sent per socket. A new call, PNSendRequest, has been added for this purpose. The function of the old SendRequest call itself remains unchanged. FUNCTION PNSendRequest (thePBptr: ATPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 userData longword User bytes <-- 22 reqTID word Transaction ID used in request --> 26 csCode word Always sendRequest <-> 28 atpSocket byte Socket to send request on or current bitmap <-> 29 atpFlags byte Control information --> 30 addrBlock longword Destination socket address --> 34 reqLength word Request size in bytes --> 36 reqPointer pointer Pointer to request data --> 40 bdsPointer pointer Pointer to response BDS --> 44 numOfBuffs byte Number of responses expected --> 45 timeOutVal byte Timeout interval <-- 46 numOf Resps byte Number of responses received <-> 47 retryCount byte Number of retries <-- 48 intBuff word Used internally The PNSendRequest call is functionally equivalent to the SendRequest call, however PNSendRequest allows you to specify, in the atpSocket field, the socket through which the request is to be sent. This socket must have been previously opened through an OpenATPSkt request (otherwise a badATPSkt error will be returned). Note that PNSendRequest requires two additional bytes of memory at the end of the parameter block, immediately following the retryCount. These bytes are for the internal use of the AppleTalk Manager and should not be modified while the PNSendRequest call is active. There is a machine-dependent limit as to the number of concurrent PNSendRequests that can be active on a given socket. If this limit is exceeded, the error tooManyReqs is returned. One additional difference between SendRequest and PNSendRequest is that a PNSendRequest can only be aborted by a PKillSendReq call (see below), whereas a SendRequest can be aborted by either a RelTCB or KillSendReq call. Result Codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls reqAborted Request cancelled by user æKY PKillSendReq æFc AppleTalk.h æT Function æD pascal OSErr PKillSendReq(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PKillSendReq((ATPPBPtr) thePBPtr,(Boolean) async); æRI V-517 æC »Aborting ATP SendRequests The RelTCB call is still supported, but only for aborting SendRequests. To abort PNSendRequests, a new call, PKillSendReq, has been added. This call will abort both SendRequests and PNSendRequests. PKillSendReq’s only argument is the queue element pointer of the request to be aborted. The queue element pointer is passed at the offset of the PKillSendReq queue element specified by aKillQE1. FUNCTION PKillSendReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always PKillSendReq --> 44 aKillQEl pointer Pointer to queue element PKillSendReq is functionally equivalent to RelTCB, except that it takes different arguments and will abort both SendRequests and PNSendRequests. To abort one of these calls, place a pointer to the queue element of the call to abort in aKillQEl and issue the PKillSendReq call. Result Codes noErr No error cbNotFound aKillQEl does not point to a SendReq or NSendReq queue element æKY PKillGetReq æFc AppleTalk.h æT Function æD pascal OSErr PKillGetReq(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = PKillGetReq((ATPPBPtr) thePBPtr,(Boolean) async); æRI V-518 æC »Aborting ATP GetRequests ATP GetRequests can now be aborted through the PKillGetReq call. This call looks and works just like the PKillSendReq call, and is used to abort a specific GetRequest call. Previously it was necessary to close the socket to abort all GetRequest calls on the socket. FUNCTION PKillGetReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always PKillGetReq --> 44 aKillQEl pointer Pointer to queue element PKillGetReq will abort a specific outstanding GetRequest call (as opposed to closing the socket, which aborts all outstanding GetRequests on that socket). The call will be completed with a reqAborted error. To abort a GetRequest, place a pointer to the queue element of the call to abort in aKillQEl and issue the PKillGetReq call. Result Codes noErr No error cbNotFound aKillQEl does not point to a GetReq queue element æKY ATPKillAllGetReq æFc AppleTalk.h æT Function æD pascal OSErr ATPKillAllGetReq(ATPPBPtr thePBPtr,Boolean async); æDT OSErr myVariable = ATPKillAllGetReq((ATPPBPtr) thePBPtr,(Boolean) async); æRI V-518 æC »Aborting ATP GetRequests ATP GetRequests can now be aborted through the PKillGetReq call. This call looks and works just like the PKillSendReq call, and is used to abort a specific GetRequest call. Previously it was necessary to close the socket to abort all GetRequest calls on the socket. FUNCTION PKillGetReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always PKillGetReq --> 44 aKillQEl pointer Pointer to queue element PKillGetReq will abort a specific outstanding GetRequest call (as opposed to closing the socket, which aborts all outstanding GetRequests on that socket). The call will be completed with a reqAborted error. To abort a GetRequest, place a pointer to the queue element of the call to abort in aKillQEl and issue the PKillGetReq call. Result Codes noErr No error cbNotFound aKillQEl does not point to a GetReq queue element æKY BuildLAPwds æFc AppleTalk.h æT Function æD pascal void BuildLAPwds(Ptr wdsPtr,Ptr dataPtr,short destHost,short prototype, short frameLen); æDT BuildLAPwds((Ptr) wdsPtr,(Ptr) dataPtr,(short) destHost,(short) prototype,() short frameLen); æRI V-514 æC This routine builds a single-frame write data structure LAP WDS for use with the PWriteLAP call. Given a buffer of length frameLen pointed to by dataPtr, it fills in the WDS pointed to by wdsPtr and sets the destination node and protocol type as indicated by destHost and protoType, respectively. The WDS indicated must contain at least two elements. æKY BuildDDPwds æFc AppleTalk.h æT Function æD pascal void BuildDDPwds(Ptr wdsPtr,Ptr headerPtr,Ptr dataPtr,const AddrBlock netAddr, short ddpType,short dataLen); æDT BuildDDPwds((Ptr) wdsPtr,(Ptr) headerPtr,(Ptr) dataPtr,(const AddrBlock) netAddr,() short ddpType,(short) dataLen); æRI V-514 æC This routine builds a single-frame write data structure DDP WDS, for use with the PWriteDDP call. Given a header buffer of at least 17 bytes pointed to by headerPtr and a data buffer of length dataLen pointed to by dataPtr, it fills in the WDS pointed to by wdsPtr, and sets the destination address and protocol type as indicated by destaddress and DDPtype, respectively. The WDS indicated must contain at least 3 elements. æKY NBPSetEntity æFc AppleTalk.h æT Function æD pascal void NBPSetEntity(Ptr buffer,Ptr nbpObject,Ptr nbpType,Ptr nbpZone); æDT NBPSetEntity((Ptr) buffer,(Ptr) nbpObject,(Ptr) nbpType,(Ptr) nbpZone); æRI V-514 æC This routine builds an NBP entity structure, for use with the PLookupNBP and PConfirmName calls. Given a buffer of at least the size of the EntityName data structure (99 bytes) pointed to by buffer, this routine sets the indicated object, type, and zone in that buffer. æKY NBPSetNTE æFc AppleTalk.h æT Function æD pascal void NBPSetNTE(Ptr ntePtr,Ptr nbpObject,Ptr nbpType,Ptr nbpZone, short socket); æDT NBPSetNTE((Ptr) ntePtr,(Ptr) nbpObject,(Ptr) nbpType,(Ptr) nbpZone,() short socket); æRI V-515 æC This routine builds an NBP names table entry, for use with the PRegisterName call. Given a names table entry of at least the size of the EntityName data structure plus nine bytes (108 bytes) pointed to by ntePtr, this routine sets the indicated object, type, zone, and socket in that names table entry. æKY GetBridgeAddress æFc AppleTalk.h æT Function æD pascal short GetBridgeAddress(void); æDT short myVariable = GetBridgeAddress()(void); æRT 132 æRI V-515, N132-2 æC This routine returns the current address of a bridge in the low byte, or zero if there is none. æKY BuildBDS æFc AppleTalk.h æT Function æD pascal short BuildBDS(Ptr buffPtr,Ptr bdsPtr,short buffSize); æDT short myVariable = BuildBDS((Ptr) buffPtr,(Ptr) bdsPtr,(short) buffSize); æRI V-515 æC This routine builds a BDS, for use with the ATP calls. Given a data buffer of length buffSize pointed to by buffPtr, it fills in the BDS pointed to by bdsPtr. The buffer will be broken up into pieces of maximum size (578 bytes). The user bytes in the BDS are not modified by this routine. This routine is provided only as a convenience; generally the caller will be able to build the BDS completely from Pascal without it. æKY MPPOpen æFc AppleTalk.h æT Function æD pascal OSErr MPPOpen(void); æDT OSErr myVariable = MPPOpen()(void); æMM æRT 224 æRI II-275 æC MPPOpen first checks whether the .MPP driver has already been loaded; if it has, MPPOpen does nothing and returns noErr. If MPP hasn’t been loaded, MPPOpen attempts to load it into the system heap. If it succeeds, it then initializes the driver’s variables and goes through the process of dynamically assigning a node ID to that Macintosh. On a Macintosh 512K or XL, it also loads the .ATP driver and NBP code into the system heap. If serial port B isn’t configured for AppleTalk, or is already in use, the .MPP driver isn’t loaded and an appropriate result code is returned. Result codes noErr No error portInUse Port B is already in use portNotCf Port B not configured for AppleTalk æKY MPPClose æFc AppleTalk.h æT Function æD pascal OSErr MPPClose(void); æDT OSErr myVariable = MPPClose()(void); æMM æRI II-275 æC MPPClose removes the .MPP driver, and any data structures associated with it, from memory. If the .ATP driver or NBP code were also installed, they’re removed as well. MPPClose also returns the use of port B to the Serial Driver. Warning: Since other co-resident programs may be using AppleTalk, it’s strongly recommended that you never use this call. MPPClose will completely disable AppleTalk; the only way to restore AppleTalk is to call MPPOpen again. æKY LAPOpenProtocol æFc AppleTalk.h æT Function æD pascal OSErr LAPOpenProtocol(ABByte theLAPType,Ptr protoPtr); æDT OSErr myVariable = LAPOpenProtocol((ABByte) theLAPType,(Ptr) protoPtr); æMM æRI II-277 æC LAPOpenProtocol adds the ALAP protocol type specified by theLAPType to the node’s protocol table. If you provide a pointer to a protocol handler in protoPtr, ALAP will send each frame with an ALAP protocol type of theLAPType to that protocol handler. If protoPtr is NIL, the default protocol handler will be used for receiving frames with an ALAP protocol type of theLAPType. In this case, to receive a frame you must call LAPRead to provide the default protocol handler with a buffer for placing the data. If, however, you’ve written your own protocol handler and protoPtr points to it, your protocol handler will have the responsibility for receiving the frame and it’s not necessary to call LAPRead. Result codes noErr No error lapProtErr Error attaching protocol type æKY LAPCloseProtocol æFc AppleTalk.h æT Function æD pascal OSErr LAPCloseProtocol(ABByte theLAPType); æDT OSErr myVariable = LAPCloseProtocol((ABByte) theLAPType); æMM æRI II-277 æC LAPCloseProtocol removes from the node’s protocol table the specified ALAP protocol type, as well as its protocol handler. Warning: Don’t close ALAP protocol type values 1 or 2. If you close these protocol types, DDP will be disabled; once disabled, the only way to restore DDP is to restart the system, or to close and then reopen AppleTalk. Result codes noErr No error lapProtErr Error detaching protocol type æKY LAPWrite æFc AppleTalk.h æT Function æD pascal OSErr LAPWrite(ATLAPRecHandle abRecord,Boolean async); æDT OSErr myVariable = LAPWrite((ATLAPRecHandle) abRecord,(Boolean) async); æMM æRI II-277 æC ABusRecord <-- abOpcode {always tLAPWrite} <-- abResult {result code} --> abUserReference {for your use} --> lapAddress.dstNodeID {destination node ID} --> lapAddress.lapProtType {ALAP protocol type} --> lapReqCount {length of frame data} --> lapDataPtr {pointer to frame data} LAPWrite sends a frame to another node. LAPReqCount and lapDataPtr specify the length and location of the data to send. The lapAddress.lapProtType field indicates the ALAP protocol type of the frame and the lapAddress.dstNodeID indicates the node ID of the node to which the frame should be sent. Note: The first two bytes of an ALAP frame’s data must contain the length in bytes of that data, including the length bytes themselves. Result codes noErr No error excessCollsns Unable to contact destination node; packet not sent ddpLenErr ALAP data length too big lapProtErr Invalid ALAP protocol type æKY LAPRead æFc AppleTalk.h æT Function æD pascal OSErr LAPRead(ATLAPRecHandle abRecord,Boolean async); æDT OSErr myVariable = LAPRead((ATLAPRecHandle) abRecord,(Boolean) async); æMM æRI II-278 æC ABusRecord <-- abOpcode {always tLAPRead} <-- abResult {result code} --> abUserReference {for your use} <-- lapAddress.dstNodeID {destination node ID} <-- lapAddress.srcNodeID {source node ID} --> lapAddress.lapProtType {ALAP protocol type} --> lapReqCount {buffer size in bytes} <-- lapActCount {number of frame data bytes actually received} --> lapDataPtr {pointer to buffer} LAPRead receives a frame from another node. LAPReqCount and lapDataPtr specify the size and location of the buffer that will receive the frame data. If the buffer isn’t large enough to hold all of the incoming frame data, the extra bytes will be discarded and buf2SmallErr will be returned. The number of bytes actually received is returned in lapActCount. Only frames with ALAP protocol type equal to lapAddress.lapProtType will be received. The node IDs of the frame’s source and destination nodes are returned in lapAddress.srcNodeID and lapAddress.dstNodeID. You can determine whether the packet was broadcast to you by examining the value of lapAddress.dstNodeID—if the packet was broadcast it’s equal to 255, otherwise it’s equal to your node ID. Note: You should issue LAPRead calls only for ALAP protocol types that were opened (via LAPOpenProtocol) to use the default protocol handler. Warning: If you close a protocol type for which there are still LAPRead calls pending, the calls will be canceled but the memory occupied by their ABusRecords will not be released. For this reason, before closing a protocol type, call LAPRdCancel to cancel any pending LAPRead calls associated with that protocol type. Result codes noErr No error buf2SmallErr Frame too large for buffer readQErr Invalid protocol type or protocol type not found in table æKY LAPRdCancel æFc AppleTalk.h æT Function æD pascal OSErr LAPRdCancel(ATLAPRecHandle abRecord); æDT OSErr myVariable = LAPRdCancel((ATLAPRecHandle) abRecord); æMM æRI II-279 æC Given the handle to the ABusRecord of a previously made LAPRead call, LAPRdCancel dequeues the LAPRead call, provided that a packet satisfying the LAPRead has not already arrived. LAPRdCancel returns noErr if the LAPRead call is successfully removed from the queue. If LAPRdCancel returns recNotFnd, check the abResult field to verify that the LAPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid protocol type or protocol type not found in table recNotFnd ABRecord not found in queue »Example This example sends an ALAP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known protocol type (in this case, 73) to receive packets, and that the destination node has a node ID of 4. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} myLAPType: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(lapSize)); myLAPType := 73; {Enter myLAPType into protocol handler table and install default handler to } { service frames of that ALAP type. No packets of that ALAP type will be } { received until we call LAPRead.} errCode := LAPOpenProtocol(myLAPType, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the protocol type') {Have we opened too many protocol types? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This data will be in the ALAP data area'; {The .MPP implementation requires that the first two bytes of the ALAP } { data field contain the length of the data, including the length bytes } { themselves.} dataLen := LENGTH(someText) + 2; buffer[0] := CHR(dataLen DIV 256); {high byte of data length} buffer[1] := CHR(dataLen MOD 256); {low byte of data length} FOR index := 1 TO dataLen - 2 DO {stuff buffer with packet data} buffer[index + 1] := someText[index]; async := FALSE; WITH myABRecord^^ DO {fill parameters in the ABusRecord} BEGIN lapAddress.lapProtType := myLAPType; lapAddress.dstNodeID := 4; lapReqCount := dataLen; lapDataPtr := @buffer; END; {Send the frame} errCode := LAPWrite(myABRecord, async); {In the case of a sync call, errCode and the abResult field of } { the myABRecord will contain the same result code. We can also } { reuse myABRecord, since we know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async LAPRead call so that we don't “hang” waiting for a } { response that may not come.} async := TRUE; WITH myABRecord^^ DO BEGIN lapAddress.lapProtType := myLAPType; {ALAP type we want to receive } lapReqCount := 600; {our buffer is maximum size} lapDataPtr := @buffer; END; errCode := LAPRead(myABRecord, async); {wait for a packet} IF errCode <> noErr THEN WRITELN('Error while trying to queue up a LAPRead') {Was the protocol handler installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the abResult } { field or just exit our code and use the event } { mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a network event} errCode := LAPCloseProtocol(myLAPType); IF errCode <> noErr THEN WRITELN('Error while closing the protocol type'); END; END; END; END; END. æKY LAPAddATQ æFc AppleTalk.h æT Function æD pascal OSErr LAPAddATQ(ATQEntryPtr theATQEntry); æDT OSErr myVariable = LAPAddATQ((ATQEntryPtr) theATQEntry); æMM æRI II-279 æC Given the handle to the ABusRecord of a previously made LAPRead call, LAPRdCancel dequeues the LAPRead call, provided that a packet satisfying the LAPRead has not already arrived. LAPRdCancel returns noErr if the LAPRead call is successfully removed from the queue. If LAPRdCancel returns recNotFnd, check the abResult field to verify that the LAPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid protocol type or protocol type not found in table recNotFnd ABRecord not found in queue »Example This example sends an ALAP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known protocol type (in this case, 73) to receive packets, and that the destination node has a node ID of 4. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} myLAPType: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(lapSize)); myLAPType := 73; {Enter myLAPType into protocol handler table and install default handler to } { service frames of that ALAP type. No packets of that ALAP type will be } { received until we call LAPRead.} errCode := LAPOpenProtocol(myLAPType, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the protocol type') {Have we opened too many protocol types? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This data will be in the ALAP data area'; {The .MPP implementation requires that the first two bytes of the ALAP } { data field contain the length of the data, including the length bytes } { themselves.} dataLen := LENGTH(someText) + 2; buffer[0] := CHR(dataLen DIV 256); {high byte of data length} buffer[1] := CHR(dataLen MOD 256); {low byte of data length} FOR index := 1 TO dataLen - 2 DO {stuff buffer with packet data} buffer[index + 1] := someText[index]; async := FALSE; WITH myABRecord^^ DO {fill parameters in the ABusRecord} BEGIN lapAddress.lapProtType := myLAPType; lapAddress.dstNodeID := 4; lapReqCount := dataLen; lapDataPtr := @buffer; END; {Send the frame} errCode := LAPWrite(myABRecord, async); {In the case of a sync call, errCode and the abResult field of } { the myABRecord will contain the same result code. We can also } { reuse myABRecord, since we know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async LAPRead call so that we don't “hang” waiting for a } { response that may not come.} async := TRUE; WITH myABRecord^^ DO BEGIN lapAddress.lapProtType := myLAPType; {ALAP type we want to receive } lapReqCount := 600; {our buffer is maximum size} lapDataPtr := @buffer; END; errCode := LAPRead(myABRecord, async); {wait for a packet} IF errCode <> noErr THEN WRITELN('Error while trying to queue up a LAPRead') {Was the protocol handler installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the abResult } { field or just exit our code and use the event } { mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a network event} errCode := LAPCloseProtocol(myLAPType); IF errCode <> noErr THEN WRITELN('Error while closing the protocol type'); END; END; END; END; END. æKY LAPRmvATQ æFc AppleTalk.h æT Function æD pascal OSErr LAPRmvATQ(ATQEntryPtr theATQEntry); æDT OSErr myVariable = LAPRmvATQ((ATQEntryPtr) theATQEntry); æMM æRI II-279 æC Given the handle to the ABusRecord of a previously made LAPRead call, LAPRdCancel dequeues the LAPRead call, provided that a packet satisfying the LAPRead has not already arrived. LAPRdCancel returns noErr if the LAPRead call is successfully removed from the queue. If LAPRdCancel returns recNotFnd, check the abResult field to verify that the LAPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid protocol type or protocol type not found in table recNotFnd ABRecord not found in queue »Example This example sends an ALAP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known protocol type (in this case, 73) to receive packets, and that the destination node has a node ID of 4. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} myLAPType: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(lapSize)); myLAPType := 73; {Enter myLAPType into protocol handler table and install default handler to } { service frames of that ALAP type. No packets of that ALAP type will be } { received until we call LAPRead.} errCode := LAPOpenProtocol(myLAPType, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the protocol type') {Have we opened too many protocol types? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This data will be in the ALAP data area'; {The .MPP implementation requires that the first two bytes of the ALAP } { data field contain the length of the data, including the length bytes } { themselves.} dataLen := LENGTH(someText) + 2; buffer[0] := CHR(dataLen DIV 256); {high byte of data length} buffer[1] := CHR(dataLen MOD 256); {low byte of data length} FOR index := 1 TO dataLen - 2 DO {stuff buffer with packet data} buffer[index + 1] := someText[index]; async := FALSE; WITH myABRecord^^ DO {fill parameters in the ABusRecord} BEGIN lapAddress.lapProtType := myLAPType; lapAddress.dstNodeID := 4; lapReqCount := dataLen; lapDataPtr := @buffer; END; {Send the frame} errCode := LAPWrite(myABRecord, async); {In the case of a sync call, errCode and the abResult field of } { the myABRecord will contain the same result code. We can also } { reuse myABRecord, since we know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async LAPRead call so that we don't “hang” waiting for a } { response that may not come.} async := TRUE; WITH myABRecord^^ DO BEGIN lapAddress.lapProtType := myLAPType; {ALAP type we want to receive } lapReqCount := 600; {our buffer is maximum size} lapDataPtr := @buffer; END; errCode := LAPRead(myABRecord, async); {wait for a packet} IF errCode <> noErr THEN WRITELN('Error while trying to queue up a LAPRead') {Was the protocol handler installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the abResult } { field or just exit our code and use the event } { mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a network event} errCode := LAPCloseProtocol(myLAPType); IF errCode <> noErr THEN WRITELN('Error while closing the protocol type'); END; END; END; END; END. æKY DDPOpenSocket æFc AppleTalk.h æT Function æD pascal OSErr DDPOpenSocket(short *theSocket,Ptr sktListener); æDT OSErr myVariable = DDPOpenSocket((short *) theSocket,(Ptr) sktListener); æMM æRI II-282 æC DDPOpenSocket adds a socket and its socket listener to the socket table. If theSocket is nonzero, it must be in the range 64 to 127, and it specifies the socket’s number; if theSocket is 0, DDPOpenSocket dynamically assigns a socket number in the range 128 to 254, and returns it in theSocket. SktListener contains a pointer to the socket listener; if it’s NIL, the default listener will be used. If you’re using the default socket listener, you must then call DDPRead to receive a datagram (in order to specify buffer space for the default socket listener). If, however, you’ve written your own socket listener and sktListener points to it, your listener will provide buffers for receiving datagrams and you shouldn’t use DDPRead calls. DDPOpenSocket will return ddpSktErr if you pass the number of an already opened socket, if you pass a socket number greater than 127, or if the socket table is full. Note: The range of static socket numbers 1 through 63 is reserved by Apple for internal use. Socket numbers 64 through 127 are available for unrestricted experimental use. Result codes noErr No error ddpSktErr Socket error æKY DDPCloseSocket æFc AppleTalk.h æT Function æD pascal OSErr DDPCloseSocket(char theSocket); æDT OSErr myVariable = DDPCloseSocket((char) theSocket); æMM æRI II-282 æC DDPCloseSocket removes the entry of the specified socket from the socket table and cancels all pending DDPRead calls that have been made for that socket. If you pass a socket number of 0, or if you attempt to close a socket that isn’t open, DDPCloseSocket will return ddpSktErr. Result codes noErr No error ddpSktErr Socket error æKY DDPRead æFc AppleTalk.h æT Function æD pascal OSErr DDPRead(ATDDPRecHandle abRecord,Boolean retCksumErrs,Boolean async); æDT OSErr myVariable = DDPRead((ATDDPRecHandle) abRecord,(Boolean) retCksumErrs,(Boolean) async); æMM æRI II-283 æC ABusRecord <-- abOpcode {always tDDPRead} <-- abResult {result code} --> abUserReference {for your use} <-- ddpType {DDP protocol type} --> ddpSocket {listening socket number} <-- ddpAddress {source socket address} --> ddpReqCount {buffer size in bytes} <-- ddpActCount {number of bytes actually received} --> ddpDataPtr {pointer to buffer} <-- ddpNodeID {original destination node ID} DDPRead receives a datagram from another socket. The size and location of the buffer that will receive the data are specified by ddpReqCount and ddpDataPtr. If the buffer isn’t large enough to hold all of the incoming frame data, the extra bytes will be discarded and buf2SmallErr will be returned. The number of bytes actually received is returned in ddpActCount. DDPSocket specifies the socket to receive the datagram (the “listening” socket). The node to which the packet was sent is returned in ddpNodeID; if the packet was broadcast ddpNodeID will contain 255. The address of the socket that sent the packet is returned in ddpAddress. If retCksumErrs is FALSE, DDPRead will discard any packets received with an invalid checksum and inform the caller of the error. If retCksumErrs is TRUE, DDPRead will deliver all packets, whether or not the checksum is valid; it will also notify the caller when there’s a checksum error. Note: The sender of the datagram must be in a different node from the receiver. You should issue DDPRead calls only for receiving datagrams for sockets opened with the default socket listener; see the description of DDPOpenSocket. Note: If the buffer provided isn’t large enough to hold all of the incoming frame data (buf2SmallErr), the checksum can’t be calculated; in this case, DDPRead will deliver packets even if retCksumErrs is FALSE. Result codes noErr No error buf2SmallErr Datagram too large for buffer cksumErr Checksum error ddpLenErr Datagram length too big ddpSktErr Socket error readQErr Invalid socket or socket not found in table æKY DDPWrite æFc AppleTalk.h æT Function æD pascal OSErr DDPWrite(ATDDPRecHandle abRecord,Boolean doChecksum,Boolean async); æDT OSErr myVariable = DDPWrite((ATDDPRecHandle) abRecord,(Boolean) doChecksum,(Boolean) async); æMM æRI II-283 æC ABusRecord <-- abOpcode {always tDDPWrite} <-- abResult {result code} --> abUserReference {for your use} --> ddpType {DDP protocol type} --> ddpSocket {source socket number} --> ddpAddress {destination socket address} --> ddpReqCount {length of datagram data} --> ddpDataPtr {pointer to buffer} DDPWrite sends a datagram to another socket. DDPReqCount and ddpDataPtr specify the length and location of the data to send. The ddpType field indicates the DDP protocol type of the frame, and ddpAddress is the complete internet address of the socket to which the datagram should be sent. DDPSocket specifies the socket from which the datagram should be sent. Datagrams sent over the internet to a node on an AppleTalk network different from the sending node’s network have an optional software checksum to detect errors that might occur inside the intermediate bridges. If doChecksum is TRUE, DDPWrite will compute this checksum; if it’s FALSE, this software checksum feature is ignored. Note: The destination socket can’t be in the same node as the program making the DDPWrite call. Result codes noErr No error ddpLenErr Datagram length too big ddpSktErr Source socket not open noBridgeErr No bridge found æKY DDPRdCancel æFc AppleTalk.h æT Function æD pascal OSErr DDPRdCancel(ATDDPRecHandle abRecord); æDT OSErr myVariable = DDPRdCancel((ATDDPRecHandle) abRecord); æMM æRI II-284 æC Given the handle to the ABusRecord of a previously made DDPRead call, DDPRdCancel dequeues the DDPRead call, provided that a packet satisfying the DDPRead hasn’t already arrived. DDPRdCancel returns noErr if the DDPRead call is successfully removed from the queue. If DDPRdCancel returns recNotFnd, check the abResult field of abRecord to verify that the DDPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid socket or socket not found in table recNotFnd ABRecord not found in queue »Example This example sends a DDP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known socket number (in this case, 30) to receive packets. Normally, you would want to use NBP to look up your destination’s socket address. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} mySocket: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async, retCksumErrs, doChecksum: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(ddpSize)); mySocket := 30; {Add mySocket to socket table and install default socket listener to service } { datagrams addressed to that socket. No packets addressed to mySocket will be } { received until we call DDPRead. } errCode := DDPOpenSocket(mySocket, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the socket') {Have we opened too many socket listeners? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This is a sample datagram'; dataLen := LENGTH(someText); FOR index := 0 TO dataLen - 1 DO {stuff buffer with packet data} myBuffer[index] := someText[index + 1]; async := FALSE; WITH myABRecord^^ DO {fill the parameters in the ABusRecord} BEGIN ddpType := 5; ddpAddress.aNet := 0; {send on “our” network} ddpAddress.aNode := 34; ddpAddress.aSocket := mySocket; ddpReqCount := dataLen; ddpDataPtr := @myBuffer; END; doChecksum := FALSE; {If packet contains a DDP long header, compute checksum and insert it into } { the header.} errCode := DDPWrite(myABRecord, doChecksum, async); {send packet} {In the case of a sync call, errCode and the abResult field of myABRecord } { will contain the same result code. We can also reuse myABRecord, since we } { know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async DDPRead call so that we don't “hang” waiting for a } { response that may not come. To cancel the async read call, we must } { close the socket associated with the call or call DDPRdCancel.} async := TRUE; retCksumErrs := TRUE; {return packets even if } { they have a checksum error} WITH myABRecord^^ DO BEGIN ddpSocket := mySocket; ddpReqCount := 600; {our reception buffer is max size} ddpDataPtr := @myBuffer; END; {Wait for a packet asynchronously} errCode := DDPRead(myABRecord, retCksumErrs, async); IF errCode <> noErr THEN WRITELN('Error while trying to queue up a DDPRead') {Was the socket listener installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the } { abResult field or just exit our code and use the } { event mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a } { network event} {If there were no errors, a packet is inside the array } { mybuffer, the length is in ddpActCount, and the } { address of the sending socket is in ddpAddress. } { Process the packet received here and report any errors.} errCode := DDPCloseSocket(mySocket); {we're done with it} IF errCode <> noErr THEN WRITELN('Error while closing the socket'); END; END; END; END; END. æKY ATPLoad æFc AppleTalk.h æT Function æD pascal OSErr ATPLoad(void); æDT OSErr myVariable = ATPLoad()(void); æMM æRT 20, 224 æRI II-290, N20-2 æC •••Refer to Technical Note #224:••• ATPLoad first verifies that the .MPP driver is loaded and running. If it isn’t, ATPLoad verifies that port B is configured for AppleTalk and isn’t in use, and then loads MPP into the system heap. ATPLoad then loads the .ATP driver, unless it’s already in memory. On a Macintosh 128K, ATPLoad reads the .ATP driver from the system resource file into the application heap; on a Macintosh 512K or XL, ATP is read into the system heap. Note: On a Macintosh 512K or XL, ATPLoad and MPPOpen perform essentially the same function. Result codes noErr No error portInUse Port B is already in use portNotCf Port B not configured for AppleTalk æKY ATPUnload æFc AppleTalk.h æT Function æD pascal OSErr ATPUnload(void); æDT OSErr myVariable = ATPUnload()(void); æRI II-290 æC ATPUnload makes the .ATP driver purgeable; the space isn’t actually released by the Memory Manager until necessary. Note: This call applies only to a Macintosh 128K; on a Macintosh 512K or Macintosh XL, ATPUnload has no effect. Result codes noErr No error æKY ATPOpenSocket æFc AppleTalk.h æT Function æD pascal OSErr ATPOpenSocket(const AddrBlock *addrRcvd,char *atpSocket); æDT OSErr myVariable = ATPOpenSocket((const AddrBlock *) addrRcvd,(char *) atpSocket); æMM æRI II-290 æC æKY ATPCloseSocket æFc AppleTalk.h æT Function æD pascal OSErr ATPCloseSocket(char atpSocket); æDT OSErr myVariable = ATPCloseSocket((char) atpSocket); æMM æRI II-291 æC ATPCloseSocket closes the responding socket whose number is specified by atpSocket. It releases the data structures associated with all pending, asynchronous calls involving that socket; these pending calls are completed immediately and return the result code sktClosed. Result codes noErr No error noDataArea Too many outstanding ATP calls æKY ATPSndRequest æFc AppleTalk.h æT Function æD pascal OSErr ATPSndRequest(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPSndRequest((ATATPRecHandle) abRecord,(Boolean) async); æMM æRI II-291 æC ABusRecord <-- abOpcode {always tATPSndRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpAddress {destination socket address} --> atpReqCount {request size in bytes} --> atpDataPtr {pointer to buffer} --> atpRspBDSPtr {pointer to response BDS} --> atpUserData {user bytes} --> atpXO {exactly-once flag} <-- atpEOM {end-of-message flag} --> atpTimeOut {retry timeout interval in seconds} --> atpRetries {maximum number of retries} --> atpNumBufs {number of elements in response BDS} <-- atpNumRsp {number of response packets actually received} ATPSndRequest sends a request to another socket. ATPAddress is the internet address of the socket to which the request should be sent. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the request information to be sent. ATPUserData contains the user bytes for the ATP header. ATPSndRequest requires you to allocate a response BDS. ATPRspBDSPtr is a pointer to the response BDS; atpNumBufs indicates the number of elements in the BDS (this is also the maximum number of response datagrams that will be accepted). The number of response datagrams actually received is returned in atpNumRsp; if a nonzero value is returned, you can examine the response BDS to determine which packets of the transaction were actually received. If the number returned is less than requested, one of the following is true: • Some of the packets have been lost and the retry count has been exceeded. • ATPEOM is TRUE; this means that the response consisted of fewer packets than were expected, but that all packets sent were received (the last packet came with the atpEOM flag set). ATPTimeOut indicates the length of time that ATPSndRequest should wait for a response before retransmitting the request. ATPRetries indicates the maximum number of retries ATPSndRequest should attempt. ATPXO should be TRUE if you want the request to be part of an exactly-once transaction. ATPSndRequest completes when either the transaction is completed or the retry count is exceeded. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls æKY ATPRequest æFc AppleTalk.h æT Function æD pascal OSErr ATPRequest(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPRequest((ATATPRecHandle) abRecord,(Boolean) async); æMM æRI II-292 æC ABusRecord <-- abOpcode {always tATPRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpAddress {destination socket address} --> atpReqCount {request size in bytes} --> atpDataPtr {pointer to buffer} <-- atpActCount {number of bytes actually received} --> atpUserData {user bytes} --> atpXO {exactly-once flag} <-- atpEOM {end-of-message flag} --> atpTimeOut {retry timeout interval in seconds} --> atpRetries {maximum number of retries} <-- atpRspUData {user bytes received in transaction response} --> atpRspBuf {pointer to response message buffer} --> atpRspSize {size of response message buffer} ATPRequest is functionally analogous to ATPSndRequest. It sends a request to another socket, but doesn’t require the caller to set up and use the BDS data structure to describe the response buffers. ATPAddress indicates the socket to which the request should be sent. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the request information to be sent. ATPUserData contains the user bytes to be sent in the request’s ATP header. ATPTimeOut indicates the length of time that ATPRequest should wait for a response before retransmitting the request. ATPRetries indicates the maximum number of retries ATPRequest should attempt. To use this call, you must have an area of contiguous buffer space that’s large enough to receive all expected datagrams. The various datagrams will be assembled in this buffer and returned to you as a complete message upon completion of the transaction. The location and size of this buffer are passed in atpRspBuf and atpRspSize. Upon completion of the call, the size of the received response message is returned in atpActCount. The user bytes received in the ATP header of the first response packet are returned in atpRspUData. ATPXO should be TRUE if you want the request to be part of an exactly-once transaction. Although you don’t provide a BDS, ATPRequest in fact creates one and calls the .ATP driver (as in an ATPSndRequest call). For this reason, the abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPRequest; you should not expect these fields to remain unaltered during or after the function’s execution. For ATPRequest to receive and correctly deliver the response as a single message, the responding end must, upon receiving the request (with an ATPGetRequest call), generate the complete response as a message in a single buffer and then call ATPResponse. Note: The responding end could also use ATPSndRsp and ATPAddRsp provided that each response packet (except the last one) contains exactly 578 ATP data bytes; the last packet in the response can contain less than 578 ATP data bytes. Also, if this method is used, only the ATP user bytes of the first response packet will be delivered to the requester; any information in the user bytes of the remaining response packets will not be delivered. ATPRequest completes when either the transaction is completed or the retry count is exceeded. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls æKY ATPReqCancel æFc AppleTalk.h æT Function æD pascal OSErr ATPReqCancel(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPReqCancel((ATATPRecHandle) abRecord,(Boolean) async); æMM æRI II-293 æC Given the handle to the ABusRecord of a previously made ATPSndRequest or ATPRequest call, ATPReqCancel dequeues the ATPSndRequest or ATPRequest call, provided that the call hasn’t already completed. ATPReqCancel returns noErr if the ATPSndRequest or ATPRequest call is successfully removed from the queue. If it returns cbNotFound, check the abResult field of abRecord to verify that the ATPSndRequest or ATPRequest call has completed and determine its outcome. Result codes noErr No error cbNotFound ATP control block not found æKY ATPGetRequest æFc AppleTalk.h æT Function æD pascal OSErr ATPGetRequest(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPGetRequest((ATATPRecHandle) abRecord,(Boolean) async); æMM æRT 20 æRI II-293, N20-2 æC ABusRecord <-- abOpcode {always tATPGetRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {listening socket number} <-- atpAddress {source socket address} --> atpReqCount {buffer size in bytes} --> atpDataPtr {pointer to buffer} <-- atpBitMap {transaction bit map} <-- atpTransID {transaction ID} <-- atpActCount {number of bytes actually received} <-- atpUserData {user bytes} <-- atpXO {exactly-once flag} ATPGetRequest sets up the mechanism to receive a request sent by either an ATPSndRequest or an ATPRequest call. ATPSocket contains the socket number of the socket that should listen for a request; this socket must already have been opened by calling ATPOpenSocket. The address of the socket from which the request was sent is returned in atpAddress. ATPDataPtr specifies a buffer to store the incoming request; atpReqCount indicates the size of the buffer in bytes. The number of bytes actually received in the request is returned in atpActCount. ATPUserData contains the user bytes from the ATP header. The transaction bit map is returned in atpBitMap. The transaction ID is returned in atpTransID. ATPXO will be TRUE if the request is part of an exactly-once transaction. ATPGetRequest completes when a request is received. To cancel an asynchronous ATPGetRequest call, you must call ATPCloseSocket, but this cancels all pending calls involving that socket. Result codes noErr No error badATPSkt Bad responding socket sktClosed Socket closed by a cancel call æKY ATPSndRsp æFc AppleTalk.h æT Function æD pascal OSErr ATPSndRsp(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPSndRsp((ATATPRecHandle) abRecord,(Boolean) async); æMM æRI II-294 æC ABusRecord <-- abOpcode {always tATPSdRsp} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpRspBDSPtr {pointer to response BDS} --> atpTransID {transaction ID} --> atpEOM {end-of-message flag} --> atpNumBufs {number of response packets being sent} --> atpBDSSize {number of elements in response BDS} ATPSndRsp sends a response to another socket. ATPSocket contains the socket number from which the response should be sent and atpAddress contains the internet address of the socket to which the response should be sent. ATPTransID must contain the transaction ID. ATPEOM is TRUE if the response BDS contains the final packet in a transaction composed of a group of packets and the number of packets in the response is less than expected. ATPRspBDSPtr points to the buffer data structure containing the responses to be sent. ATPBDSSize indicates the number of elements in the response BDS, and must be in the range 1 to 8. ATPNumBufs indicates the number of response packets being sent with this call, and must be in the range 0 to 8. Note: In some situations, you may want to send only part (or possibly none) of your response message back immediately. For instance, you might be requested to send back seven disk blocks, but have only enough internal memory to store one block. In this case, set atpBDSSize to 7 (total number of response packets), atpNumBufs to 0 (number of response packets currently being sent), and call ATPSndRsp. Then as you read in one block at a time, call ATPAddRsp until all seven response datagrams have been sent. During exactly-once transactions, ATPSndRsp won’t complete until the release packet is received or the release timer expires. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls badBuffNum Bad sequence number æKY ATPAddRsp æFc AppleTalk.h æT Function æD pascal OSErr ATPAddRsp(ATATPRecHandle abRecord); æDT OSErr myVariable = ATPAddRsp((ATATPRecHandle) abRecord); æMM æRI II-295 æC ABusRecord <-- abOpcode {always tATPAddRsp} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpReqCount {buffer size in bytes} --> atpDataPtr {pointer to buffer} --> atpTransID {transaction ID} --> atpUserData {user bytes} --> atpEOM {end-of-message flag} --> atpNumRsp {sequence number} ATPAddRsp sends one additional response packet to a socket that has already been sent the initial part of a response via ATPSndRsp. ATPSocket contains the socket number from which the response should be sent and atpAddress contains the internet address of the socket to which the response should be sent. ATPTransID must contain the transaction ID. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the information to send; atpNumRsp is the sequence number of the response. ATPEOM is TRUE if this response datagram is the final packet in a transaction composed of a group of packets. ATPUserData contains the user bytes to be sent in this response datagram’s ATP header. Note: No BDS is needed with ATPAddRsp because all pertinent information is passed within the record. Result codes noErr No error badATPSkt Bad responding socket badBuffNum Bad sequence number noSendResp ATPAddRsp issued before ATPSndRsp noDataArea Too many outstanding ATP calls æKY ATPResponse æFc AppleTalk.h æT Function æD pascal OSErr ATPResponse(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPResponse((ATATPRecHandle) abRecord,(Boolean) async); æMM æRT 20 æRI II-296, N20-2 æC ABusRecord <-- abOpcode {always tATPResponse} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpTransID {transaction ID) --> atpRspUData {user bytes sent in transaction response} --> atpRspBuf {pointer to response message buffer} --> atpRspSize {size of response message buffer} ATPResponse is functionally analogous to ATPSndRsp. It sends a response to another socket, but doesn’t require the caller to provide a BDS. ATPAddress must contain the complete network address of the socket to which the response should be sent (taken from the data provided by an ATPGetRequest call). ATPTransID must contain the transaction ID. ATPSocket indicates the socket from which the response should be sent (the socket on which the corresponding ATPGetRequest was issued). ATPRspBuf points to the buffer containing the response message; the size of this buffer must be passed in atpRspSize. The four user bytes to be sent in the ATP header of the first response packet are passed in atpRspUData. The last packet of the transaction response is sent with the EOM flag set. Although you don’t provide a BDS, ATPResponse in fact creates one and calls the .ATP driver (as in an ATPSndRsp call). For this reason, the abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPResponse; you should not expect these fields to remain unaltered during or after the function’s execution. During exactly-once transactions ATPResponse won’t complete until the release packet is received or the release timer expires. Warning: The maximum permissible size of the response message is 4624 bytes. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received atpLenErr Response too big sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls æKY ATPRspCancel æFc AppleTalk.h æT Function æD pascal OSErr ATPRspCancel(ATATPRecHandle abRecord,Boolean async); æDT OSErr myVariable = ATPRspCancel((ATATPRecHandle) abRecord,(Boolean) async); æMM æRI II-296 æC Given the handle to the ABusRecord of a previously made ATPSndRsp or ATPResponse call, ATPRspCancel dequeues the ATPSndRsp or ATPResponse call, provided that the call hasn’t already completed. ATPRspCancel returns noErr if the ATPSndRsp or ATPResponse call is successfully removed from the queue. If it returns cbNotFound, check the abResult field of abRecord to verify that the ATPSndRsp or ATPResponse call has completed and determine its outcome. Result codes noErr No error cbNotFound ATP control block not found »Example This example shows the requesting side of an ATP transaction that asks for a 512-byte disk block from the responding end. The block number of the file is a byte and is contained in myBuffer[0]. VAR myABRecord: ABRecHandle; myBDSPtr: BDSPtr; myBuffer: PACKED ARRAY [0..511] OF CHAR; errCode: INTEGER; async: BOOLEAN; BEGIN errCode := ATPLoad; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Prepare the BDS; allocate space for a one-element BDS} myBDSPtr := BDSPtr(NewPtr(SIZEOF(BDSElement))); WITH myBDSPtr^[0] DO BEGIN buffSize := 512; {size of our buffer used in reception} buffPtr := @myBuffer; {pointer to the buffer} END; {Prepare the ABusRecord} myBuffer[0] := CHR(1); {requesting disk block number 1} myABRecord := ABRecHandle(NewHandle(atpSize)); WITH myABRecord^^ DO BEGIN atpAddress.aNet := 0; atpAddress.aNode := 30; {we probably got this from an NBP call} atpAddress.aSocket := 15; {socket to send request to} atpReqCount := 1; {size of request data field (disk block #)} atpDataPtr := @myBuffer; {ptr to request to be sent} atpRspBDSPtr := @myBDSPtr; atpUserData := 0; {for your use} atpXO := FALSE; {at-least-once service} atpTimeOut := 5; {5-second timeout} atpRetries := 3; {3 retries; request will be sent 4 times max} atpNumBufs := 1; {we're only expecting 1 block to be returned} END; async := FALSE; {Send the request and wait for the response} errCode := ATPSndRequest(myABRecord, async); IF errCode <> noErr THEN WRITELN('An error occurred in the ATPSndRequest call') ELSE BEGIN {The disk block requested is now in myBuffer. We can verify } { that atpNumRsp contains 1, meaning one response received.} . . . END; END; END. æKY NBPRegister æFc AppleTalk.h æT Function æD pascal OSErr NBPRegister(ATNBPRecHandle abRecord,Boolean async); æDT OSErr myVariable = NBPRegister((ATNBPRecHandle) abRecord,(Boolean) async); æMM æRT 20 æRI II-299, N20-2 æC ABusRecord <-- abOpcode {always tNBPRegister} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} --> nbpBufPtr {pointer to buffer} --> nbpBufSize {buffer size in bytes} --> nbpAddress.aSocket {socket address} --> nbpRetransmitInfo {retransmission information} NBPRegister adds the name and address of an entity to the node’s names table. NBPEntityPtr points to a variable of type EntityName containing the entity’s name. If the name is already registered, NBPRegister returns the result code nbpDuplicate. NBPAddress indicates the socket for which the name should be registered. NBPBufPtr and nbpBufSize specify the location and size of a buffer for NBP to use internally. While the variable of type EntityName is declared as three 32-byte strings, only the actual characters of the name are placed in the buffer pointed to by nbpBufPtr. For this reason, nbpBufSize needs only to be equal to the actual length of the name, plus an additional 12 bytes for use by NBP. Warning: This buffer must not be altered or released until the name is removed from the names table via an NBPRemove call. If you allocate the buffer through a NewHandle call, you must lock it as long as the name is registered. Warning: The zone field of the entity name must be set to the meta-character “*”. Result codes noErr No error nbpDuplicate Duplicate name already exists æKY NBPLookup æFc AppleTalk.h æT Function æD pascal OSErr NBPLookup(ATNBPRecHandle abRecord,Boolean async); æDT OSErr myVariable = NBPLookup((ATNBPRecHandle) abRecord,(Boolean) async); æMM æRT 9, 20 æRI II-300, N9-1, 2, N20-2 æC ABusRecord <-- abOpcode {always tNBPLookup} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} --> nbpBufPtr {pointer to buffer} --> nbpBufSize {buffer size in bytes} <-> nbpDataField {number of addresses received} --> nbpRetransmitInfo {retransmission information} NBPLookup returns the addresses of all entities with a specified name. NBPEntityPtr points to a variable of type EntityName containing the name of the entity whose address should be returned. (Meta-characters are allowed in the entity name.) NBPBufPtr and nbpBufSize contain the location and size of an area of memory in which the entity names and their corresponding addresses should be returned. NBPDataField indicates the maximum number of matching names to find addresses for; the actual number of addresses found is returned in nbpDataField. NBPRetransmitInfo contains the retry interval and the retry count. When specifying nbpBufSize, for each NBP tuple expected, allow space for the actual characters of the name, the address, and four bytes for use by NBP. Result codes noErr No error nbpBuffOvr Buffer overflow æKY NBPExtract æFc AppleTalk.h æT Function æD pascal OSErr NBPExtract(Ptr theBuffer,short numInBuf,short whichOne,EntityName *abEntity, AddrBlock *address); æDT OSErr myVariable = NBPExtract((Ptr) theBuffer,(short) numInBuf,(short) whichOne,(EntityName *) abEntity,( AddrBlock) * address); æMM æRI II-300,V-515 æC This routine is provided in the alternate interface, but can be used as provided for extracting NBP entity names from a look-up response buffer. NBPExtract returns one address from the list of addresses returned by NBPLookup. TheBuffer and numInBuf indicate the location and number of tuples in the buffer. WhichOne specifies which one of the tuples in the buffer should be returned in the abEntity and address parameters. Result codes noErr No error extractErr Can’t find tuple in buffer æKY NBPConfirm æFc AppleTalk.h æT Function æD pascal OSErr NBPConfirm(ATNBPRecHandle abRecord,Boolean async); æDT OSErr myVariable = NBPConfirm((ATNBPRecHandle) abRecord,(Boolean) async); æMM æRT 9 æRI II-301, N9-2 æC ABusRecord <-- abOpcode {always tNBPConfirm} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} <-- nbpDataField {socket number} --> nbpAddress {socket address} --> nbpRetransmitInfo {retransmission information} NBPConfirm confirms that an entity known by name and address still exists (is still entered in the names directory). NBPEntityPtr points to a variable of type EntityName that contains the name to confirm, and nbpAddress specifies the address to be confirmed. (No meta-characters are allowed in the entity name.) NBPRetransmitInfo contains the retry interval and the retry count. The socket number of the entity is returned in nbpDataField. NBPConfirm is more efficient than NBPLookup in terms of network traffic. Result codes noErr No error nbpConfDiff Name confirmed for different socket nbpNoConfirm Name not confirmed æKY NBPRemove æFc AppleTalk.h æT Function æD pascal OSErr NBPRemove(EntityPtr abEntity); æDT OSErr myVariable = NBPRemove((EntityPtr) abEntity); æMM æRI II-301 æC NBPRemove removes an entity name from the names table of the given entity’s node. Result codes noErr No error nbpNotFound Name not found æKY NBPLoad æFc AppleTalk.h æT Function æD pascal OSErr NBPLoad(void); æDT OSErr myVariable = NBPLoad()(void); æMM æRI II-301 æC On a Macintosh 128K, NBPLoad reads the NBP code from the system resource file into the application heap. On a Macintosh 512K or XL, NBPLoad has no effect since the NBP code should have already been loaded when the .MPP driver was opened. Normally you’ll never need to call NBPLoad, because the AppleTalk Manager calls it when necessary. Result codes noErr No error æKY NBPUnload æFc AppleTalk.h æT Function æD pascal OSErr NBPUnload(void); æDT OSErr myVariable = NBPUnload()(void); æMM æRI II-301 æC On a Macintosh 128K, NBPUnload makes the NBP code purgeable; the space isn’t actually released by the Memory Manager until necessary. On a Macintosh 512K or Macintosh XL, NBPUnload has no effect. Result codes noErr No error »Example This example of NBP registers our node as a print spooler, searches for any print spoolers registered on the network, and then extracts the information for the first one found. CONST mySocket = 20; VAR myABRecord: ABRecHandle; myEntity: EntityName; entityAddr: AddrBlock; nbpNamePtr: Ptr; myBuffer: PACKED ARRAY [0..999] OF CHAR; errCode: INTEGER; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(nbpSize)); {Set up our entity name to register} WITH myEntity DO BEGIN objStr := 'Gene Station'; {we are called 'Gene Station' } typeStr := 'PrintSpooler'; { and are of type 'PrintSpooler'} zoneStr := '*'; {Allocate data space for the entity name (used by NBP)} nbpNamePtr := NewPtr(LENGTH(objStr) + LENGTH(typeStr) + LENGTH(zoneStr) + 12); END; {Set up the ABusRecord for the NBPRegister call} WITH myABRecord^^ DO BEGIN nbpEntityPtr := @myEntity; nbpBufPtr := nbpNamePtr; {buffer used by NBP internally} nbpBufSize := nbpNameBufSize; nbpAddress.aSocket := mySocket; {socket to register us on} nbpRetransmitInfo.retransInterval := 8; {retransmit every 64 } nbpRetransmitInfo.retransCount := 3; { ticks and try 3 times} END; async := FALSE; errCode := NBPRegister(myABRecord, async); IF errCode <> noErr THEN WRITELN('Error occurred in the NBPRegister call') {Maybe the name is already registered somewhere else on the } { network.} ELSE BEGIN {Now that we've registered our name, find others of type } { 'PrintSpooler'.} WITH myEntity DO BEGIN objStr := '='; {any one of type } typeStr := 'PrintSpooler'; { “PrintSpooler” } zoneStr := '*'; { in our zone} END; WITH myABRecord^^ DO BEGIN nbpEntityPtr := @myEntity; nbpBufPtr := @myBuffer; {buffer to place responses in} nbpBufSize := SIZEOF(myBuffer); {The field nbpDataField, before the NBPLookup call, represents an } { approximate number of responses. After the call, nbpDataField } { contains the actual number of responses received.} nbpDataField := 100; {we want about 100 responses back} END; errCode := NBPLookup(myABRecord, async); {make sync call} IF errCode <> noErr THEN WRITELN('An error occurred in the NBPLookup') {Did the buffer overflow?} ELSE BEGIN {Get the first reply} errCode := NBPExtract(@mybuffer, myABRecord^^.nbpDataField, 1, myEntity, entityAddr); {The socket address and name of the entity are returned here. If we } { want all of them, we'll have to loop for each one in the buffer.} IF errCode <> noErr THEN WRITELN('Error in NBPExtract'); {Maybe the one we wanted wasn't in the buffer} END; END; END; END. æKY GetNodeAddress æFc AppleTalk.h æT Function æD pascal OSErr GetNodeAddress(short *myNode,short *myNet); æDT OSErr myVariable = GetNodeAddress((short *) myNode,(short *) myNet); æRI II-303 æC GetNodeAddress returns the current node ID and network number of the caller. If the .MPP driver isn’t installed, it returns noMPPErr. If myNet contains 0, this means that a bridge hasn’t yet been found. Result codes noErr No error noMPPErr MPP driver not installed æKY IsMPPOpen æFc AppleTalk.h æT Function æD pascal Boolean IsMPPOpen(void); æDT Boolean myVariable = IsMPPOpen()(void); æRI II-304 æC [Not in ROM] IsMPPOpen returns TRUE if the .MPP driver is loaded and running. æKY IsATPOpen æFc AppleTalk.h æT Function æD pascal Boolean IsATPOpen(void); æDT Boolean myVariable = IsATPOpen()(void); æRI II-304 æC [Not in ROM] IsATPOpen returns TRUE if the .ATP driver is loaded and running. æKY ATEvent æFc AppleTalk.h æT Function æD pascal void ATEvent(long event,Ptr infoPtr); æDT ATEvent((long) event,(Ptr) infoPtr); æRI II-304 æC [Not in ROM] IsATPOpen returns TRUE if the .ATP driver is loaded and running. æKY ATPreFlightEvent æFc AppleTalk.h æT Function æD pascal OSErr ATPreFlightEvent(long event,long cancel,Ptr infoPtr); æDT OSErr myVariable = ATPreFlightEvent((long) event,(long) cancel,(Ptr) infoPtr); æRI II-304 æC [Not in ROM] IsATPOpen returns TRUE if the .ATP driver is loaded and running. æKY Assert.h æC assert #include <Assert.h> void assert (int expression); Description The assert; macro allows your program to send diagnostic messages to the user, depending on the evaluation of expression. If expression is false, assert provides an error message, and then calls the abort function. The format for this message is FILE myfile.c; Line 108 ##assertion failed: i<j The assert macro can be activated using the NDEBUG macro. If NDEBUG is turned off, assert will evaluate expression. Note The message pointed to by assert is an executable MPW command. When the command is executed, it will open the source file containing the assert and highlight the assert statement. Example #include <assert.h> main() { int i,j; i = foo(); j = 3; assert (i<100); /* This depends on the compile-time */ /* setting of NDEBUG. If */ /* NDEBUG is defined, the assert */ /* statement is not passed from the */ /* preprocessor to the compiler */ #undef NDEBUG /* Turn off NDEBUG */ #include <assert.h> assert (i<j); /* This assert is turned on */ #define NDEBUG /* Turn on NDEBUG */ #include <assert.h> j = foo(); assert (j <100); /* This assert is turned off */ } See also abort æKY assert æFc Assert.h æC #include <Assert.h> void assert (int expression); Description The assert; macro allows your program to send diagnostic messages to the user, depending on the evaluation of expression. If expression is false, assert provides an error message, and then calls the abort function. The format for this message is FILE myfile.c; Line 108 ##assertion failed: i<j The assert macro can be activated using the NDEBUG macro. If NDEBUG is turned off, assert will evaluate expression. Note The message pointed to by assert is an executable MPW command. When the command is executed, it will open the source file containing the assert and highlight the assert statement. Example #include <assert.h> main() { int i,j; i = foo(); j = 3; assert (i<100); /* This depends on the compile-time */ /* setting of NDEBUG. If */ /* NDEBUG is defined, the assert */ /* statement is not passed from the */ /* preprocessor to the compiler */ #undef NDEBUG /* Turn off NDEBUG */ #include <assert.h> assert (i<j); /* This assert is turned on */ #define NDEBUG /* Turn on NDEBUG */ #include <assert.h> j = foo(); assert (j <100); /* This assert is turned off */ } See also abort æKY assertæ æDT void myVariable = assert ((int) expression); æKY Balloons.h æKL HMBalloonPict HMBalloonRect HMExtractHelpMsg HMGetBalloons HMGetBalloonWindow HMGetDialogResID HMGetFont HMGetFontSize HMGetHelpMenuHandle HMGetIndHelpMsg HMGetMenuResID HMIsBalloon HMRemoveBalloon HMScanTemplateItems HMSetBalloons HMSetDialogResID HMSetFont HMSetFontSize HMSetMenuResID HMShowBalloon HMShowMenuBalloon helpItem hmAbsoluteCoords hmBalloonAborted hmBalloonHelpVersion hmCloseViewActive hmDefaultOptions hmHelpDisabled hmHelpManagerNotInited hmMatchInTitle HMMessageRecord HMMessageRecPtr hmNoBalloonUp hmOperationUnsupported hmSameAsLastBalloon hmSaveBitsNoWindow hmSaveBitsWindow hmSkippedBalloon HMStringResType hmUnknownHelpType hmUseSubID hmWrongVersion kBalloonWDEFID kHMAboutHelpItem kHMCheckedItem kHMCompareItem kHMDialogResType kHMDisabledItem kHMEnabledItem kHMFinderApplResType kHMHelpID kHMHelpMenuID kHMMenuResType khmmPict khmmPictHandle khmmString khmmStringRes khmmSTRRes khmmTEHandle khmmTERes kHMNamedResourceItem kHMOtherItem kHMOverrideResType kHMPictItem kHMRectListResType kHMRegularWindow kHMSaveBitsNoWindow kHMSaveBitsWindow kHMShowBalloonsItem kHMSkipItem kHMStringItem kHMStringResItem kHMSTRResItem kHMTEResItem kHMTEStyleResType kHMTETextResType kHMTrackCntlItem kHMWindListResType æKY hmBalloonHelpVersion æFc Balloons.h æT æD hmBalloonHelpVersion = 0x0002, /* The real version of the Help Manager */ æC æKY hmHelpDisabled æFc Balloons.h æT æD hmHelpDisabled = -850, /* Show Balloons mode was off, call to routine ignored */ æC æKY hmBalloonAborted æFc Balloons.h æT æD hmBalloonAborted = -853, /* Returned if mouse was moving or mouse wasn't in window port rect */ æC æKY hmSameAsLastBalloon æFc Balloons.h æT æD hmSameAsLastBalloon = -854, /* Returned from HMShowMenuBalloon if menu & item is same as last time */ æC æKY hmHelpManagerNotInited æFc Balloons.h æT æD hmHelpManagerNotInited = -855, /* Returned from HMGetHelpMenuHandle if help menu not setup */ æC æKY hmSkippedBalloon æFc Balloons.h æT æD hmSkippedBalloon = -857, /* Returned from calls if helpmsg specified a skip balloon */ æC æKY hmWrongVersion æFc Balloons.h æT æD hmWrongVersion = -858, /* Returned if help mgr resource was the wrong version */ æC æKY hmUnknownHelpType æFc Balloons.h æT æD hmUnknownHelpType = -859, /* Returned if help msg record contained a bad type */ æC æKY hmOperationUnsupported æFc Balloons.h æT æD hmOperationUnsupported = -861, /* Returned from HMShowBalloon call if bad method passed to routine */ æC æKY hmNoBalloonUp æFc Balloons.h æT æD hmNoBalloonUp = -862, /* Returned from HMRemoveBalloon if no balloon was visible when call was made */ æC æKY hmCloseViewActive æFc Balloons.h æT æD hmCloseViewActive = -863, /* Returned from HMRemoveBalloon if CloseView was active */ æC æKY kHMHelpMenuID æFc Balloons.h æT æD kHMHelpMenuID = -16490, /* Resource ID and menu ID of help menu */ æC æKY kHMAboutHelpItem æFc Balloons.h æT æD kHMAboutHelpItem = 1, /* help menu item number of About Balloon Help… */ æC æKY kHMShowBalloonsItem æFc Balloons.h æT æD kHMShowBalloonsItem = 3, /* help menu item number of Show/Hide Balloons */ æC æKY kHMHelpID æFc Balloons.h æT æD kHMHelpID = -5696, /* ID of various Help Mgr package resources (in Pack14 range) */ æC æKY kBalloonWDEFID æFc Balloons.h æT æD kBalloonWDEFID = 126, /* Resource ID of the WDEF proc used in standard balloons */ æC æKY helpItem æFc Balloons.h æT æD helpItem = 1, /* key value in DITL template that corresponds to the help item */ æC æKY hmDefaultOptions æFc Balloons.h æT æD hmDefaultOptions = 0, /* default options for help manager resources */ æC æKY hmUseSubID æFc Balloons.h æT æD hmUseSubID = 1, /* treat resID's in resources as subID's of driver base ID */ æC æKY hmAbsoluteCoords æFc Balloons.h æT æD hmAbsoluteCoords = 2, /* ignore window port origin and treat rectangles as absolute coords */ æC æKY hmSaveBitsNoWindow æFc Balloons.h æT æD hmSaveBitsNoWindow = 4, /* don't create a window, just blast bits on screen. No update event is generated */ æC æKY hmSaveBitsWindow æFc Balloons.h æT æD hmSaveBitsWindow = 8, /* create a window, but restore bits behind window when window goes away */ æC æKY hmMatchInTitle æFc Balloons.h æT æD hmMatchInTitle = 16, /* for hwin resources, match string anywhere in window title string */ æC æKY kHMStringItem æFc Balloons.h æT æD kHMStringItem = 1, /* pstring used in resource */ æC æKY kHMPictItem æFc Balloons.h æT æD kHMPictItem = 2, /* 'PICT' ResID used in resource */ æC æKY kHMStringResItem æFc Balloons.h æT æD kHMStringResItem = 3, /* 'STR#' ResID & index used in resource */ æC æKY kHMTEResItem æFc Balloons.h æT æD kHMTEResItem = 6, /* Styled Text Edit ResID used in resource ('TEXT' & 'styl') */ æC æKY kHMSTRResItem æFc Balloons.h æT æD kHMSTRResItem = 7, /* 'STR ' ResID used in resource */ æC æKY kHMSkipItem æFc Balloons.h æT æD kHMSkipItem = 256, /* don't display a balloon */ æC æKY kHMCompareItem æFc Balloons.h æT æD kHMCompareItem = 512, /* Compare pstring in menu item w/ PString in resource item */ æC æKY kHMNamedResourceItem æFc Balloons.h æT æD kHMNamedResourceItem = 1024, /* Use pstring in menu item to get 'STR#', 'PICT', or 'STR ' resource ('hmnu' only) */ æC æKY kHMTrackCntlItem æFc Balloons.h æT æD kHMTrackCntlItem = 2048, /* Reserved */ æC æKY khmmString æFc Balloons.h æT æD khmmString = 1, /* help message contains a PString */ æC æKY khmmPict æFc Balloons.h æT æD khmmPict = 2, /* help message contains a resource ID to a 'PICT' resource */ æC æKY khmmStringRes æFc Balloons.h æT æD khmmStringRes = 3, /* help message contains a res ID & index to a 'STR#' resource */ æC æKY khmmTEHandle æFc Balloons.h æT æD khmmTEHandle = 4, /* help message contains a Text Edit handle */ æC æKY khmmPictHandle æFc Balloons.h æT æD khmmPictHandle = 5, /* help message contains a Picture handle */ æC æKY khmmTERes æFc Balloons.h æT æD khmmTERes = 6, /* help message contains a res ID to 'TEXT' & 'styl' resources */ æC æKY khmmSTRRes æFc Balloons.h æT æD khmmSTRRes = 7, /* help message contains a res ID to a 'STR ' resource */ æC æKY kHMTETextResType æFc Balloons.h æT #define æD #define kHMTETextResType 'TEXT' /* Resource Type of text data for styled TE record w/o style info */ æC æKY kHMTEStyleResType æFc Balloons.h æT #define æD #define kHMTEStyleResType 'styl' /* Resource Type of style information for styled TE record */ æC æKY kHMEnabledItem æFc Balloons.h æT æD kHMEnabledItem = 0, /* item is enabled, but not checked or control value = 0 */ æC æKY kHMDisabledItem æFc Balloons.h æT æD kHMDisabledItem = 1, /* item is disabled, grayed in menus or disabled in dialogs */ æC æKY kHMCheckedItem æFc Balloons.h æT æD kHMCheckedItem = 2, /* item is enabled, and checked or control value = 1 */ æC æKY kHMOtherItem æFc Balloons.h æT æD kHMOtherItem = 3, /* item is enabled, and control value > 1 */ æC æKY kHMMenuResType æFc Balloons.h æT #define æD #define kHMMenuResType 'hmnu' /* ResType of help resource for supporting menus */ æC æKY kHMDialogResType æFc Balloons.h æT #define æD #define kHMDialogResType 'hdlg' /* ResType of help resource for supporting dialogs */ æC æKY kHMWindListResType æFc Balloons.h æT #define æD #define kHMWindListResType 'hwin' /* ResType of help resource for supporting windows */ æC æKY kHMRectListResType æFc Balloons.h æT #define æD #define kHMRectListResType 'hrct' /* ResType of help resource for rectangles in windows */ æC æKY kHMOverrideResType æFc Balloons.h æT #define æD #define kHMOverrideResType 'hovr' /* ResType of help resource for overriding system balloons */ æC æKY kHMFinderApplResType æFc Balloons.h æT #define æD #define kHMFinderApplResType 'hfdr' /* ResType of help resource for custom balloon in Finder */ æC æKY kHMRegularWindow æFc Balloons.h æT æD kHMRegularWindow = 0, /* Create a regular window floating above all windows */ æC æKY kHMSaveBitsNoWindow æFc Balloons.h æT æD kHMSaveBitsNoWindow = 1, /* Just save the bits and draw (for MDEF calls) */ æC æKY kHMSaveBitsWindow æFc Balloons.h æT æD kHMSaveBitsWindow = 2, /* Regular window, save bits behind, AND generate update event */ æC æKY HMStringResType æFc Balloons.h æT struct æD struct HMStringResType { short hmmResID; short hmmIndex; }; typedef struct HMStringResType HMStringResType; æC æKY HMMessageRecord HMMessageRecPtr æFc Balloons.h æT struct æD struct HMMessageRecord { short hmmHelpType; union { char hmmString[256]; short hmmPict; Handle hmmTEHandle; HMStringResType hmmStringRes; short hmmPictRes; Handle hmmPictHandle; short hmmTERes; short hmmSTRRes; } u; }; typedef struct HMMessageRecord HMMessageRecord; typedef HMMessageRecord *HMMessageRecPtr; æC æKY HMGetHelpMenuHandle æFc Balloons.h æT Function æD pascal OSErr HMGetHelpMenuHandle(MenuHandle *mh) = {0x303C,0x0200,_Pack14}; æDT OSErr myVariable = HMGetHelpMenuHandle((MenuHandle *) mh); æC æKY HMShowBalloon æFc Balloons.h æT Function æD pascal OSErr HMShowBalloon(const HMMessageRecord *aHelpMsg, Point tip, RectPtr alternateRect, Ptr tipProc, short theProc, short variant, short method) = {0x303C,0x0B01,_Pack14}; æDT OSErr myVariable = HMShowBalloon((const HMMessageRecord *) aHelpMsg,() Point tip,() RectPtr alternateRect,() Ptr tipProc,() short theProc,() short variant,() short method); æC æKY HMRemoveBalloon æFc Balloons.h æT Function æD pascal OSErr HMRemoveBalloon(void) = {0x303C,0x0002,_Pack14}; æDT OSErr myVariable = HMRemoveBalloon()(void); æC æKY HMGetBalloons æFc Balloons.h æT Function æD pascal Boolean HMGetBalloons(void) = {0x303C,0x0003,_Pack14}; æDT Boolean myVariable = HMGetBalloons()(void); æC æKY HMSetBalloons æFc Balloons.h æT Function æD pascal OSErr HMSetBalloons(Boolean flag) = {0x303C,0x0104,_Pack14}; æDT OSErr myVariable = HMSetBalloons((Boolean) flag); æC æKY HMShowMenuBalloon æFc Balloons.h æT Function æD pascal OSErr HMShowMenuBalloon(short itemNum, short itemMenuID, long itemFlags, long itemReserved, Point tip, RectPtr alternateRect, Ptr tipProc, short theProc, short variant) = {0x303C,0x0E05,_Pack14}; æDT OSErr myVariable = HMShowMenuBalloon((short) itemNum,() short itemMenuID,() long itemFlags,() long itemReserved,() Point tip,() RectPtr alternateRect,() Ptr tipProc,() short theProc,() short variant); æC æKY HMGetIndHelpMsg æFc Balloons.h æT Function æD pascal OSErr HMGetIndHelpMsg(ResType whichType, short whichResID, short whichMsg, short whichState, long *options, Point *tip, Rect *altRect, short *theProc, short *variant, HMMessageRecord *aHelpMsg, short *count) = {0x303C,0x1306,_Pack14}; æDT OSErr myVariable = HMGetIndHelpMsg((ResType) whichType,() short whichResID,() short whichMsg,() short whichState,( long) * options,( Point) * tip,( Rect) * altRect,( short) * theProc,( short) * variant,( HMMessageRecord) * aHelpMsg,( short) * count); æC æKY HMIsBalloon æFc Balloons.h æT Function æD pascal Boolean HMIsBalloon(void) = {0x303C,0x0007,_Pack14}; æDT Boolean myVariable = HMIsBalloon()(void); æC æKY HMSetFont æFc Balloons.h æT Function æD pascal OSErr HMSetFont(short font) = {0x303C,0x0108,_Pack14}; æDT OSErr myVariable = HMSetFont((short) font); æC æKY HMSetFontSize æFc Balloons.h æT Function æD pascal OSErr HMSetFontSize(short fontSize) = {0x303C,0x0109,_Pack14}; æDT OSErr myVariable = HMSetFontSize((short) fontSize); æC æKY HMGetFont æFc Balloons.h æT Function æD pascal OSErr HMGetFont(short *font) = {0x303C,0x020A,_Pack14}; æDT OSErr myVariable = HMGetFont((short *) font); æC æKY HMGetFontSize æFc Balloons.h æT Function æD pascal OSErr HMGetFontSize(short *fontSize) = {0x303C,0x020B,_Pack14}; æDT OSErr myVariable = HMGetFontSize((short *) fontSize); æC æKY HMSetDialogResID æFc Balloons.h æT Function æD pascal OSErr HMSetDialogResID(short resID) = {0x303C,0x010C,_Pack14}; æDT OSErr myVariable = HMSetDialogResID((short) resID); æC æKY HMSetMenuResID æFc Balloons.h æT Function æD pascal OSErr HMSetMenuResID(short menuID, short resID) = {0x303C,0x020D,_Pack14}; æDT OSErr myVariable = HMSetMenuResID((short) menuID,() short resID); æC æKY HMBalloonRect æFc Balloons.h æT Function æD pascal OSErr HMBalloonRect(const HMMessageRecord *aHelpMsg, Rect *coolRect) = {0x303C,0x040E,_Pack14}; æDT OSErr myVariable = HMBalloonRect((const HMMessageRecord *) aHelpMsg,( Rect) * coolRect); æC æKY HMBalloonPict æFc Balloons.h æT Function æD pascal OSErr HMBalloonPict(const HMMessageRecord *aHelpMsg, PicHandle *coolPict) = {0x303C,0x040F,_Pack14}; æDT OSErr myVariable = HMBalloonPict((const HMMessageRecord *) aHelpMsg,( PicHandle) * coolPict); æC æKY HMScanTemplateItems æFc Balloons.h æT Function æD pascal OSErr HMScanTemplateItems(short whichID, short whichResFile, ResType whichType) = {0x303C,0x0410,_Pack14}; æDT OSErr myVariable = HMScanTemplateItems((short) whichID,() short whichResFile,() ResType whichType); æC æKY HMExtractHelpMsg æFc Balloons.h æT Function æD pascal OSErr HMExtractHelpMsg(ResType whichType,short whichResID,short whichMsg, short whichState,HMMessageRecord *aHelpMsg) = {0x303C,0x0711,_Pack14}; æDT OSErr myVariable = HMExtractHelpMsg((ResType) whichType,(short) whichResID,(short) whichMsg,() short whichState,(HMMessageRecord *) aHelpMsg); æC æKY HMGetDialogResID æFc Balloons.h æT Function æD pascal OSErr HMGetDialogResID(short *resID) = {0x303C,0x0213,_Pack14}; æDT OSErr myVariable = HMGetDialogResID((short *) resID); æC æKY HMGetMenuResID æFc Balloons.h æT Function æD pascal OSErr HMGetMenuResID(short menuID,short *resID) = {0x303C,0x0314,_Pack14}; æDT OSErr myVariable = HMGetMenuResID((short) menuID,(short *) resID); æC æKY HMGetBalloonWindow æFc Balloons.h æT Function æD pascal OSErr HMGetBalloonWindow(WindowPtr *window) = {0x303C,0x0215,_Pack14}; æDT OSErr myVariable = HMGetBalloonWindow((WindowPtr *) window); æC æKY Controls.h æKL DisposeControl dragcontrol DragControl Draw1Control DrawControls findcontrol FindControl GetAuxCtl GetCRefCon GetCTitle getctitle GetCtlAction GetCtlMax GetCtlMin GetCtlValue GetCVariant GetNewControl HideControl HiliteControl KillControls MoveControl newcontrol NewControl SetCRefCon SetCTitle setctitle SetCtlAction SetCtlColor SetCtlMax SetCtlMin SetCtlValue ShowControl SizeControl testcontrol TestControl TrackControl trackcontrol UpdateControls UpdtControl autoTrack AuxCtlHandle AuxCtlPtr AuxCtlRec calcCntlRgn calcCRgns calcThumbRgn cBodyColor CCTabHandle CCTabPtr cFrameColor checkBoxProc ControlHandle ControlPtr ControlRecord cTextColor cThumbColor CtlCTab dispCntl dragCntl drawCntl hAxisOnly inButton inCheckBox inDownButton initCntl inLabel inMenu inPageDown inPageUp inThumb inTriangle inUpButton noConstraint popupMenuProc popupTitleCenterJust popupTitleLeftJust popupTitleRightJust posCntl pushButProc radioButProc scrollBarProc testCntl thumbCntl useWFont vAxisOnly æKY pushButProc æFc Controls.h æT æD pushButProc = 0, æC æKY checkBoxProc æFc Controls.h æT æD checkBoxProc = 1, æC æKY radioButProc æFc Controls.h æT æD radioButProc = 2, æC æKY useWFont æFc Controls.h æT æD useWFont = 8, æC æKY scrollBarProc æFc Controls.h æT æD scrollBarProc = 16, æC æKY inButton æFc Controls.h æT æD inButton = 10, æC æKY inCheckBox æFc Controls.h æT æD inCheckBox = 11, æC æKY inUpButton æFc Controls.h æT æD inUpButton = 20, æC æKY inDownButton æFc Controls.h æT æD inDownButton = 21, æC æKY inPageUp æFc Controls.h æT æD inPageUp = 22, æC æKY inPageDown æFc Controls.h æT æD inPageDown = 23, æC æKY inThumb æFc Controls.h æT æD inThumb = 129, æC æKY popupMenuProc æFc Controls.h æT æD popupMenuProc = 1008, /* 63 * 16 */ æC æKY inLabel æFc Controls.h æT æD inLabel = 1, æC æKY inMenu æFc Controls.h æT æD inMenu = 2, æC æKY inTriangle æFc Controls.h æT æD inTriangle = 4, æC æKY popupTitleLeftJust æFc Controls.h æT æD popupTitleLeftJust = 0x00000000, æC æKY popupTitleCenterJust æFc Controls.h æT æD popupTitleCenterJust = 0x00000001, æC æKY popupTitleRightJust æFc Controls.h æT æD popupTitleRightJust = 0x000000FF, æC æKY noConstraint æFc Controls.h æT æD noConstraint = 0, æC æKY hAxisOnly æFc Controls.h æT æD hAxisOnly = 1, æC æKY vAxisOnly æFc Controls.h æT æD vAxisOnly = 2, æC æKY drawCntl æFc Controls.h æT æD drawCntl = 0, æC æKY testCntl æFc Controls.h æT æD testCntl = 1, æC æKY calcCRgns æFc Controls.h æT æD calcCRgns = 2, æC æKY initCntl æFc Controls.h æT æD initCntl = 3, æC æKY dispCntl æFc Controls.h æT æD dispCntl = 4, æC æKY posCntl æFc Controls.h æT æD posCntl = 5, æC æKY thumbCntl æFc Controls.h æT æD thumbCntl = 6, æC æKY dragCntl æFc Controls.h æT æD dragCntl = 7, æC æKY autoTrack æFc Controls.h æT æD autoTrack = 8, æC æKY calcCntlRgn æFc Controls.h æT æD calcCntlRgn = 10, æC æKY calcThumbRgn æFc Controls.h æT æD calcThumbRgn = 11, æC æKY cFrameColor æFc Controls.h æT æD cFrameColor = 0, æC æKY cBodyColor æFc Controls.h æT æD cBodyColor = 1, æC æKY cTextColor æFc Controls.h æT æD cTextColor = 2, æC æKY cThumbColor æFc Controls.h æT æD cThumbColor = 3, æC æKY ControlRecord ControlPtr ControlHandle æFc Controls.h æT struct æD struct ControlRecord { struct ControlRecord **nextControl; WindowPtr contrlOwner; Rect contrlRect; unsigned char contrlVis; unsigned char contrlHilite; short contrlValue; short contrlMin; short contrlMax; Handle contrlDefProc; Handle contrlData; ProcPtr contrlAction; long contrlRfCon; Str255 contrlTitle; }; typedef struct ControlRecord ControlRecord; typedef ControlRecord *ControlPtr, **ControlHandle; æC Every control is represented internally by a control record containing all pertinent information about that control. The control record contains the following: • A pointer to the window the control belongs to. • A handle to the next control in the window’s control list. • A handle to the control definition function. • The control’s title, if any. • A rectangle that completely encloses the control, which determines the control’s size and location within its window. The entire control, including the title of a check box or radio button, is drawn inside this rectangle. • An indication of whether the control is currently active and how it’s to be highlighted. • The current setting of the control (if this type of control retains a setting) and the minimum and maximum values the setting can assume. For check boxes and radio buttons, a setting of 0 means the control is off and 1 means it’s on. The control record also contains an indication of whether the control is currently visible or invisible. These terms refer only to whether the control is drawn in its window, not to whether you can see it on the screen. A control may be “visible” and still not appear on the screen, because it’s obscured by overlapping windows or other objects. There’s a field in the control record for a pointer to the control’s default action procedure. An action procedure defines some action to be performed repeatedly for as long as the user holds down the mouse button inside the control. The default action procedure may be used by the Control Manager function TrackControl if you call it without passing a pointer to an action procedure; this is discussed in detail in the description of TrackControl in the “Control Manager Routines” section. Finally, the control record includes a 32-bit reference value field, which is reserved for use by your application. You specify an initial reference value when you create a control, and can then read or change the reference value whenever you wish. The data type for a control record is called ControlRecord. A control record is referred to by a handle: TYPE ControlPtr = ^ControlRecord; ControlHandle = ^ControlPtr; The Control Manager functions for creating a control return a handle to a newly allocated control record; thereafter, your program should normally refer to the control by this handle. Most of the Control Manager routines expect a control handle as their first parameter. You can store into and access most of a control record’s fields with Control Manager routines, so normally you don’t have to know the exact field names. However, if you want more information about the exact structure of a control record—if you’re defining your own control types, for instance—it’s given below. _______________________________________________________________________________ »The ControlRecord Data Type The ControlRecord data type is defined as follows: TYPE ControlRecord = PACKED RECORD nextControl: ControlHandle; {next control} contrlOwner: WindowPtr; {control's window} contrlRect: Rect; {enclosing rectangle} contrlVis: Byte; {255 if visible} contrlHilite: Byte; {highlight state} contrlValue: INTEGER; {control's current setting} contrlMin: INTEGER; {control's minimum setting} contrlMax: INTEGER; {control's maximum setting} contrlDefProc: Handle; {control definition function} contrlData: Handle; {data used by contrlDefProc} contrlAction: ProcPtr; {default action procedure} contrlRfCon: LONGINT; {control's reference value} contrlTitle: Str255 {control's title} END; NextControl is a handle to the next control associated with this control’s window. All the controls belonging to a given window are kept in a linked list, beginning in the controlList field of the window record and chained together through the nextControl fields of the individual control records. The end of the list is marked by a NIL value; as new controls are created, they’re added to the beginning of the list. ContrlOwner is a pointer to the window that this control belongs to. ContrlRect is the rectangle that completely encloses the control, in the local coordinates of the control’s window. When contrlVis is 0, the control is currently invisible; when it’s 255, the control is visible. ContrlHilite specifies whether and how the control is to be highlighted, indicating whether it’s active or inactive. The HiliteControl procedure lets you set this field; see the description of HiliteControl for more information about the meaning of the field’s value. ContrlValue is the control’s current setting. For check boxes and radio buttons, 0 means the control is off and 1 means it’s on. For dials, the fields contrlMin and contrlMax define the range of possible settings; contrlValue may take on any value within that range. Other (custom) control types can use these three fields as they see fit. ContrlDefProc is a handle to the control definition function for this type of control. When you create a control, you identify its type with a control definition ID, which is converted into a handle to the control definition function and stored in the contrlDefProc field. Thereafter, the Control Manager uses this handle to access the definition function; you should never need to refer to this field directly. Note: When not running in 32-bit mode, the high-order byte of the contrlDefProc field contains some additional information that the Control Manager gets from the control definition ID; for details, see the section “Defining Your Own Controls”. ContrlData is reserved for use by the control definition function, typically to hold additional information specific to a particular control type. For example, the standard definition function for scroll bars uses this field for a handle to the region containing the scroll bar’s thumb. If no more than four bytes of additional information are needed, the definition function can store the information directly in the contrlData field rather than use a handle. ContrlAction is a pointer to the control’s default action procedure, if any. The Control Manager function TrackControl may call this procedure to respond to the user’s dragging the mouse inside the control. ContrlRfCon is the control’s reference value field, which the application may store into and access for any purpose. ContrlTitle is the control’s title, if any. æKY CtlCTab CCTabPtr CCTabHandle æFc Controls.h æT struct æD struct CtlCTab { long ccSeed; /*reserved*/ short ccRider; /*see what you have done - reserved*/ short ctSize; /*usually 3 for controls*/ ColorSpec ctTable[4]; }; typedef struct CtlCTab CtlCTab; typedef CtlCTab *CCTabPtr, **CCTabHandle; æC The contents and meaning of a control’s color table are determined by its control definition function (see “The Control Color Table Resource” section). The CTabHandle parameter used in the Color Control Manager routines provides a handle to the control color table. The components of a control color table are defined as follows: TYPE CCTabHandle = ^CCTabPtr; CCTabPtr = ^CtlCTab; CtlCTab = RECORD ccSeed: LONGINT; {not used for controls} ccRider: INTEGER; {not used for controls} ctSize: INTEGER; {number of entries in table –1} ctTable: cSpecArray {array of ColorSpec records} END; Field descriptions ccSeed The ccSeed field is unused in control color tables. ccRider The ccRider field is unused in control color tables. ctSize The ctSize field defines the number of elements in the table, minus one. For controls drawn with the standard definition procedure, this field is always 3. ctTable The ctTable field holds an array of colorSpec records. Each colorSpec is made up of a partIdentifier field and a partRGB field. The partIdentifier field holds an integer which associates an RGBColor to a particular part of the control. The definition procedures attempt to find the appropriate part identifier when preparing to draw a part. If that part identifier is not found, the first color in the table is used to draw the part. The part identifiers can appear in any order in the table. The partRGB field specifies a standard RGB color record, indicating what absolute color will be used to draw the control part found in the partIdentifier field. A standard control color table is shown in Figure 6. •••Refer to Figure 6.••• Figure 6–Control Color Table The 'cctb' resource is an exact image of this control table data structure, and is stored in the same format as 'clut' color table resources. Standard buttons, check boxes, and radio buttons use a four-element color table with part identifiers as shown below: cFrameColor (0) Frame color cBodyColor (1) Fill color for body of control cTextColor (2) Text color cThumbColor (3) Unused When highlighted, plain buttons exchange their body and text colors (colors 1 and 2); check boxes and radio buttons change their appearance without changing colors. All three types indicate deactivation by dimming their text with no change in colors. Standard scroll bars use a four-element color table with part identifiers as shown below: cFrameColor (0) Frame color, foreground color for shaft and arrows cBodyColor (1 Background color for shaft and arrows cTextColor (2) Unused cThumbColor (3) Fill color for thumb When highlighted, the arrows are filled with the foreground color (color 0) within the arrow outline. A deactivated scroll bar shows no indicator, and displays its shaft in solid background color (color 1), with no pattern. The 'cctb' resource = 0 is read into the application heap when the application starts, and serves as the default control color table. The last record in the auxiliary control list points to the default 'cctb' resource. When drawing a control, the standard control definition function searches the list for an auxiliary control record whose acOwner points to the control being drawn. If it finds such a record, it uses the color table designated by that record; if it doesn’t find one before reaching the default record at the end of the list, it uses the default color table instead. All types of controls share the same default record. The default auxiliary control record is recognized by NIL values in both its acNext and acOwner fields; the application must not change these fields. A nonstandard control definition function can use color tables of any desired size and define their contents in any way it wishes, except that part indices 1 to 127 are reserved for system definition. Any such nonstandard function should take care to bypass the defaulting mechanism just described, by allocating an explicit auxiliary record for every control it creates. æKY AuxCtlRec AuxCtlPtr AuxCtlHandle æFc Controls.h æT struct æD struct AuxCtlRec { Handle acNext; /*handle to next AuxCtlRec*/ ControlHandle acOwner; /*handle for aux record's control*/ CCTabHandle acCTable; /*color table for this control*/ short acFlags; /*misc flag byte*/ long acReserved; /*reserved for use by Apple*/ long acRefCon; /*for use by application*/ }; typedef struct AuxCtlRec AuxCtlRec; typedef AuxCtlRec *AuxCtlPtr, **AuxCtlHandle; æC The information needed for drawing controls in color is kept in a linked list of auxiliary control records, beginning in the global variable AuxCtlHead. (Notice that there is just one global list for all controls in all windows, not a separate one for each window.) Each window record has a handle to the list of controls. Figure 5 shows the auxiliary control list structure. •••Refer to Figure 5.••• Figure 5–Auxiliary Control List Each auxiliary control record is a relocatable object residing in the application heap. The most important information it holds is a handle to the control’s individual color table (see the “Control Color Tables” section). The rest of the record consists of a link to the next record in the list, a field that identifies the control’s owner, a 4-byte field reserved for future expansion, and a 4-byte reference constant for use by the application: TYPE AuxCtlHandle = ^AuxCtlPtr; AuxCtlPtr = ^AuxCtlRec; AuxCtlRec = RECORD acNext: AuxCtlHandle; {handle to next record in list} acOwner: ControlHandle; {handle to owning control} acCTable: CCTabHandle; {handle to control's color } { table} acFlags: INTEGER; {miscellaneous flags; reserved} acReserved: LONGINT; {reserved for future expansion} acRefCon: LONGINT {reserved for application use} END; Field descriptions acNext The acNext field contains a handle to the next record in the auxiliary control list. acOwner The acOwner field contains the handle of the control to which this auxiliary record belongs. Used as an ID field. acCTable The acCTable contains the handle to the control’s color table (see “Control Color Tables” below). acFlags The acFlags field contains miscellaneous flags for use by the Control Manager; this field is reserved. acReserved The acReserved field is reserved for future expansion; this must be set to 0 for future compatibility. acRefCon The acRefCon field is a reference constant for use by the application. Not every control needs an auxiliary control record. When an application is started, a resource containing a default color table is loaded from the system resource file; this resource defines a standard set of control colors. Since there is no InitControls routine, this happens when an application calls InitWindows. Separate auxiliary control records are needed only for controls whose color usage differs from the default. Each such nonstandard control must have its own auxiliary record, even if it uses the same colors as another control. This allows two or more auxiliary records to share the same control color table. If the control color table is a resource, it won’t be deleted by DisposeControl. When using an auxiliary record that is not stored as a resource, the application should not deallocate the color table if another control is still using it. A control created from scratch will initially have no auxiliary control record. If it is to use nonstandard colors, it must be given an auxiliary record and a color table with SetCtlColor (see the “Control Manager Routines” section). Such a control should normally be made invisible at creation and then displayed with ShowControl after the colors are set. For controls created from a 'CNTL' resource, the color table can be specified as a resource as well. See the section titled “The Control Color Table Resource”. A/UX systems: When using 32-bit mode. every control has its own auxiliary record. If there is no specific set of control colors for this control, the acCTable will point to the default color table. æKY NewControl æFc Controls.h æT Function æTN A954 æD pascal ControlHandle NewControl(WindowPtr theWindow,const Rect *boundsRect, ConstStr255Param title,Boolean visible,short value,short min,short max, short procID,long refCon) = 0xA954; æDT ControlHandle myVariable = NewControl((WindowPtr) theWindow,(const Rect *) boundsRect,() ConstStr255Param title,(Boolean) visible,(short) value,(short) min,(short) max,() short procID,(long) refCon); æMM æRI I-319, P-112, 114, 177 æC NewControl creates a control, adds it to the beginning of theWindow’s control list, and returns a handle to the new control. The values passed as parameters are stored in the corresponding fields of the control record, as described below. The field that determines highlighting is set to 0 (no highlighting) and the pointer to the default action procedure is set to NIL (none). Note: The control definition function may do additional initialization, including changing any of the fields of the control record. The only standard control for which additional initialization is done is the scroll bar; its control definition function allocates space for a region to hold the thumb and stores the region handle in the contrlData field of the control record. TheWindow is the window the new control will belong to. All coordinates pertaining to the control will be interpreted in this window’s local coordinate system. BoundsRect, given in theWindow’s local coordinates, is the rectangle that encloses the control and thus determines its size and location. Note the following about the enclosing rectangle for the standard controls: • Simple buttons are drawn to fit the rectangle exactly. (The control definition function calls the QuickDraw procedure FrameRoundRect.) To allow for the tallest characters in the system font, there should be at least a 20-point difference between the top and bottom coordinates of the rectangle. • For check boxes and radio buttons, there should be at least a 16-point difference between the top and bottom coordinates. • By convention, scroll bars are 16 pixels wide, so there should be a 16-point difference between the left and right (or top and bottom) coordinates. (If there isn’t, the scroll bar will be scaled to fit the rectangle.) A standard scroll bar should be at least 48 pixels long, to allow room for the scroll arrows and thumb. Title is the control’s title, if any (if none, you can just pass the empty string as the title). Be sure the title will fit in the control’s enclosing rectangle; if it won’t it will be truncated on the right for check boxes and radio buttons, or centered and truncated on both ends for simple buttons. Note: Some non-Roman systems write text from right-to-left, in which case radio buttons and check boxes are drawn with their titles on the left of the control. They are also truncated on the left. See the Script Manager chapter for more information. If the visible parameter is TRUE, NewControl draws the control. Note: It does not use the standard window updating mechanism, but instead draws the control immediately in the window. The min and max parameters define the control’s range of possible settings; the value parameter gives the initial setting. For controls that don’t retain a setting, such as buttons, the values you supply for these parameters will be stored in the control record but will never be used. So it doesn’t matter what values you give for those controls—0 for all three parameters will do. For controls that just retain an on-or-off setting, such as check boxes or radio buttons, min should be 0 (meaning the control is off) and max should be 1 (meaning it’s on). For dials, you can specify whatever values are appropriate for min, max, and value. ProcID is the control definition ID, which leads to the control definition function for this type of control. (The function is read into memory if it isn’t already in memory.) The control definition IDs for the standard control types are listed above under “Controls and Resources”. Control definition IDs for custom control types are discussed later under “Defining Your Own Controls”. RefCon is the control’s reference value, set and used only by your application. æKY SetCTitle æFc Controls.h æT Function æTN A95F æD pascal void SetCTitle(ControlHandle theControl,ConstStr255Param title) = 0xA95F; æDT SetCTitle((ControlHandle) theControl,(ConstStr255Param) title); æMM æRI I-321 æC SetCTitle sets theControl’s title to the given string and redraws the control. æKY GetCTitle æFc Controls.h æT Function æTN A95E æD pascal void GetCTitle(ControlHandle theControl,Str255 title) = 0xA95E; æDT GetCTitle((ControlHandle) theControl,(Str255) title); æRI I-321 æC GetCTitle returns theControl’s title as the value of the title parameter. æKY GetNewControl æFc Controls.h æT Function æTN A9BE æD pascal ControlHandle GetNewControl(short controlID,WindowPtr owner) = 0xA9BE; æDT ControlHandle myVariable = GetNewControl((short) controlID,(WindowPtr) owner); æMM æRT 203 æRI I-321, P-112, 113, 114, 172 æC GetNewControl creates a control from a control template stored in a resource file, adds it to the beginning of theWindow’s control list, and returns a handle to the new control. ControlID is the resource ID of the template. GetNewControl works exactly the same as NewControl (above), except that it gets the initial values for the new control’s fields from the specified control template instead of accepting them as parameters. If the control template can’t be read from the resource file, GetNewControl returns NIL. It releases the memory occupied by the resource before returning. The system default control colors are stored in the System file and ROMResources as 'cctb' resource = 0. By including a 'cctb' resource = 0 in your application, it is possible to change the default colors that will be used for all controls, unless a specific 'cctb' exists for a control defined within the application. When you use GetNewControl for the control resource 'CNTL', GetNewControl will attempt to load a 'cctb' resource with the same ID as the 'CNTL' resource ID, if one is present. It then executes the SetCtlColor call. The following part identifiers for control elements should be present in the ColorSpec.value field: cFrameColor (0) Frame color cBodyColor (1) Fill color for body of control cTextColor (2) Text color cThumbColor (3) Thumb color These identifiers may be present in any order; for instance, the text or indicator color values may be stored before the fill and frame colors in the ColorSpec record structure. If a part identifier is not found, then the first color in the color table will be used. æKY DisposeControl æFc Controls.h æT Function æTN A955 æD pascal void DisposeControl(ControlHandle theControl) = 0xA955; æDT DisposeControl((ControlHandle) theControl); æMM æRI I-321, P-168 æC Assembly-language note: The macro you invoke to call DisposeControl from assembly language is named _DisposControl. DisposeControl removes theControl from the screen, deletes it from its window’s control list, and releases the memory occupied by the control record and any data structures associated with the control. æKY KillControls æFc Controls.h æT Function æTN A956 æD pascal void KillControls(WindowPtr theWindow) = 0xA956; æDT KillControls((WindowPtr) theWindow); æMM æRI I-321, P-113, 175 æC KillControls disposes of all controls associated with theWindow by calling DisposeControl (above) for each. Note: Remember that the Window Manager procedures CloseWindow and DisposeWindow automatically dispose of all controls associated with the given window. æKY HideControl æFc Controls.h æT Function æTN A958 æD pascal void HideControl(ControlHandle theControl) = 0xA958; æDT HideControl((ControlHandle) theControl); æMM æRI I-322, P-113, 114, 174 æC HideControl makes theControl invisible. It fills the region the control occupies within its window with the background pattern of the window’s grafPort. It also adds the control’s enclosing rectangle to the window’s update region, so that anything else that was previously obscured by the control will reappear on the screen. If the control is already invisible, HideControl has no effect. æKY ShowControl æFc Controls.h æT Function æTN A957 æD pascal void ShowControl(ControlHandle theControl) = 0xA957; æDT ShowControl((ControlHandle) theControl); æMM æRT 197 æRI I-322, P-113, 114, 181 æC ShowControl makes theControl visible. The control is drawn in its window but may be completely or partially obscured by overlapping windows or other objects. If the control is already visible, ShowControl has no effect. æKY DrawControls æFc Controls.h æT Function æTN A969 æD pascal void DrawControls(WindowPtr theWindow) = 0xA969; æDT DrawControls((WindowPtr) theWindow); æRT 203 æRI I-322, P-169 æC DrawControls draws all controls currently visible in theWindow. The controls are drawn in reverse order of creation; thus in case of overlap the earliest-created controls appear frontmost in the window. Note: Window Manager routines such as SelectWindow, ShowWindow, and BringToFront do not automatically call DrawControls to display the window’s controls. They just add the appropriate regions to the window’s update region, generating an update event. Your program should always call DrawControls explicitly upon receiving an update event for a window that contains controls. æKY Draw1Control æFc Controls.h æT Function æTN A96D æD pascal void Draw1Control(ControlHandle theControl) = 0xA96D; æDT Draw1Control((ControlHandle) theControl); æMM æRI IV-53 æC [128K ROM] Draw1Control draws the specified control if it’s visible within the window. æKY HiliteControl æFc Controls.h æT Function æTN A95D æD pascal void HiliteControl(ControlHandle theControl,short hiliteState) = 0xA95D; æDT HiliteControl((ControlHandle) theControl,(short) hiliteState); æMM æRI I-322 æC HiliteControl changes the way theControl is highlighted. HiliteState has one of the following values: • The value 0 means no highlighting. (The control is active.) • A value between 1 and 253 is interpreted as a part code designating the part of the (active) control to be highlighted. • The value 255 means that the control is to be made inactive and highlighted accordingly. Note: The value 254 should not be used; this value is reserved for future use. HiliteControl calls the control definition function to redraw the control with its new highlighting. æKY UpdtControl æFc Controls.h æT Function æTN A953 æD pascal void UpdtControl(WindowPtr theWindow,RgnHandle updateRgn) = 0xA953; æDT UpdtControl((WindowPtr) theWindow,(RgnHandle) updateRgn); æMM æRI IV-53 æC [128K ROM] UpdtControl is a faster version of the DrawControls procedure. Instead of drawing all of the controls in theWindow, UpdtControl draws only the controls that are in the specified update region. UpdtControl is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port (for more details, see the BeginUpdate procedure in the Window Manager chapter). Note: In general, controls are in a dialog box and are automatically drawn by the DrawDialog procedure. æKY UpdateControls æFc Controls.h æT Function æTN A953 æD pascal void UpdateControls(WindowPtr theWindow,RgnHandle updateRgn) = 0xA953; æDT UpdateControls((WindowPtr) theWindow,(RgnHandle) updateRgn); æMM æRI IV-53 æC [128K ROM] UpdtControl is a faster version of the DrawControls procedure. Instead of drawing all of the controls in theWindow, UpdtControl draws only the controls that are in the specified update region. UpdtControl is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port (for more details, see the BeginUpdate procedure in the Window Manager chapter). Note: In general, controls are in a dialog box and are automatically drawn by the DrawDialog procedure. æKY MoveControl æFc Controls.h æT Function æTN A959 æD pascal void MoveControl(ControlHandle theControl,short h,short v) = 0xA959; æDT MoveControl((ControlHandle) theControl,(short) h,(short) v); æMM æRI I-325, P-113, 176 æC MoveControl moves theControl to a new location within its window. The top left corner of the control’s enclosing rectangle is moved to the horizontal and vertical coordinates h and v (given in the local coordinates of the control’s window); the bottom right corner is adjusted accordingly, to keep the size of the rectangle the same as before. If the control is currently visible, it’s hidden and then redrawn at its new location. æKY SizeControl æFc Controls.h æT Function æTN A95C æD pascal void SizeControl(ControlHandle theControl,short w,short h) = 0xA95C; æDT SizeControl((ControlHandle) theControl,(short) w,(short) h); æMM æRI I-326, P-113, 181 æC SizeControl changes the size of theControl’s enclosing rectangle. The bottom right corner of the rectangle is adjusted to set the rectangle’s width and height to the number of pixels specified by w and h; the position of the top left corner is not changed. If the control is currently visible, it’s hidden and then redrawn in its new size. æKY SetCtlValue æFc Controls.h æT Function æTN A963 æD pascal void SetCtlValue(ControlHandle theControl,short theValue) = 0xA963; æDT SetCtlValue((ControlHandle) theControl,(short) theValue); æMM æRT 197 æRI I-326 æC SetCtlValue sets theControl’s current setting to theValue and redraws the control to reflect the new setting. For check boxes and radio buttons, the value 1 fills the control with the appropriate mark, and 0 clears it. For scroll bars, SetCtlValue redraws the thumb where appropriate. If the specified value is out of range, it’s forced to the nearest endpoint of the current range (that is, if theValue is less than the minimum setting, SetCtlValue sets the current setting to the minimum; if theValue is greater than the maximum setting, it sets the current setting to the maximum). æKY GetCtlValue æFc Controls.h æT Function æTN A960 æD pascal short GetCtlValue(ControlHandle theControl) = 0xA960; æDT short myVariable = GetCtlValue((ControlHandle) theControl); æRI I-326, P-114, 171 æC GetCtlValue returns theControl’s current setting. æKY SetCtlMin æFc Controls.h æT Function æTN A964 æD pascal void SetCtlMin(ControlHandle theControl,short minValue) = 0xA964; æDT SetCtlMin((ControlHandle) theControl,(short) minValue); æMM æRI I-326 æC Assembly-language note: The macro you invoke to call SetCtlMin from assembly language is named _SetMinCtl. SetCtlMin sets theControl’s minimum setting to minValue and redraws the control to reflect the new range. If the control’s current setting is less than minValue, the setting is changed to the new minimum. æKY GetCtlMin æFc Controls.h æT Function æTN A961 æD pascal short GetCtlMin(ControlHandle theControl) = 0xA961; æDT short myVariable = GetCtlMin((ControlHandle) theControl); æRI I-327 æC Assembly-language note: The macro you invoke to call GetCtlMin from assembly language is named _GetMinCtl. GetCtlMin returns theControl’s minimum setting. æKY SetCtlMax æFc Controls.h æT Function æTN A965 æD pascal void SetCtlMax(ControlHandle theControl,short maxValue) = 0xA965; æDT SetCtlMax((ControlHandle) theControl,(short) maxValue); æMM æRI I-327 æC Assembly-language note: The macro you invoke to call SetCtlMax from assembly language is named _SetMaxCtl. SetCtlMax sets theControl’s maximum setting to maxValue and redraws the control to reflect the new range. If the control’s current setting is greater than maxValue, the setting is changed to the new maximum. Note: If you set the maximum setting of a scroll bar equal to its minimum setting, the control definition function will make the scroll bar inactive. æKY GetCtlMax æFc Controls.h æT Function æTN A962 æD pascal short GetCtlMax(ControlHandle theControl) = 0xA962; æDT short myVariable = GetCtlMax((ControlHandle) theControl); æRI I-327 æC Assembly-language note: The macro you invoke to call GetCtlMax from assembly language is named _GetMaxCtl. GetCtlMax returns theControl’s maximum setting. æKY SetCRefCon æFc Controls.h æT Function æTN A95B æD pascal void SetCRefCon(ControlHandle theControl,long data) = 0xA95B; æDT SetCRefCon((ControlHandle) theControl,(long) data); æRI I-327 æC SetCRefCon sets theControl’s reference value to the given data. æKY GetCRefCon æFc Controls.h æT Function æTN A95A æD pascal long GetCRefCon(ControlHandle theControl) = 0xA95A; æDT long myVariable = GetCRefCon((ControlHandle) theControl); æRI I-327 æC GetCRefCon returns theControl’s current reference value. æKY SetCtlAction æFc Controls.h æT Function æTN A96B æD pascal void SetCtlAction(ControlHandle theControl,ProcPtr actionProc) = 0xA96B; æDT SetCtlAction((ControlHandle) theControl,(ProcPtr) actionProc); æRI I-328 æC SetCtlAction sets theControl’s default action procedure to actionProc. æKY GetCtlAction æFc Controls.h æT Function æTN A96A æD pascal ProcPtr GetCtlAction(ControlHandle theControl) = 0xA96A; æDT ProcPtr myVariable = GetCtlAction((ControlHandle) theControl); æRI I-328, IV-53 æC GetCtlAction returns a pointer to theControl’s default action procedure, if any. (It returns whatever is in that field of the control record.) æKY DragControl æFc Controls.h æT Function æTN A967 æD pascal void DragControl(ControlHandle theControl,Point startPt,const Rect *limitRect, const Rect *slopRect,short axis) = 0xA967; æDT DragControl((ControlHandle) theControl,(Point) startPt,(const Rect *) limitRect,( const Rect) * slopRect,(short) axis); æMM æRI I-325 æC Called with the mouse button down inside theControl, DragControl pulls a dotted outline of the control around the screen, following the movements of the mouse until the button is released. When the mouse button is released, DragControl calls MoveControl to move the control to the location to which it was dragged. Note: Before beginning to follow the mouse, DragControl calls the control definition function to allow it to do its own “custom dragging” if it chooses. If the definition function doesn’t choose to do any custom dragging, DragControl uses the default method of dragging described here. The startPt, limitRect, slopRect, and axis parameters have the same meaning as for the Window Manager function DragGrayRgn. These parameters are reviewed briefly below; see the description of DragGrayRgn in the Window Manager chapter for more details. • StartPt is assumed to be the point where the mouse button was originally pressed, in the local coordinates of the control’s window. • LimitRect limits the travel of the control’s outline, and should normally coincide with or be contained within the window’s content region. • SlopRect allows the user some “slop” in moving the mouse; it should completely enclose limitRect. • The axis parameter allows you to constrain the control’s motion to only one axis. It has one of the following values: CONST noConstraint = 0; {no constraint} hAxisOnly = 1; {horizontal axis only} vAxisOnly = 2; {vertical axis only} Assembly-language note: Like TrackControl, DragControl invokes the macro _DragTheRgn, so you can use the global variables DragHook and DragPattern. æKY TestControl æFc Controls.h æT Function æTN A966 æD pascal short TestControl(ControlHandle theControl,Point thePt) = 0xA966; æDT short myVariable = TestControl((ControlHandle) theControl,(Point) thePt); æMM æRI I-325 æC If theControl is visible and active, TestControl tests which part of the control contains thePoint (in the local coordinates of the control’s window); it returns the corresponding part code, or 0 if the point is outside the control. If the control is invisible or inactive, TestControl returns 0. TestControl is called by FindControl and TrackControl; normally you won’t need to call it yourself. æKY TrackControl æFc Controls.h æT Function æTN A968 æD pascal short TrackControl(ControlHandle theControl,Point thePoint,ProcPtr actionProc) = 0xA968; æDT short myVariable = TrackControl((ControlHandle) theControl,(Point) thePoint,(ProcPtr) actionProc); æMM æRI I-323, P-114, 184 æC When the mouse button is pressed in a visible, active control, the application should call TrackControl with theControl equal to the control handle and startPt equal to the point where the mouse button was pressed (in the local coordinates of the control’s window). TrackControl follows the movements of the mouse and responds in whatever way is appropriate until the mouse button is released; the exact response depends on the type of control and the part of the control in which the mouse button was pressed. If highlighting is appropriate, TrackControl does the highlighting, and undoes it before returning. When the mouse button is released, TrackControl returns with the part code if the mouse is in the same part of the control that it was originally in, or with 0 if not (in which case the application should do nothing). If the mouse button was pressed in an indicator, TrackControl drags a dotted outline of it to follow the mouse. When the mouse button is released, TrackControl calls the control definition function to reposition the control’s indicator. The control definition function for scroll bars responds by redrawing the thumb, calculating the control’s current setting based on the new relative position of the thumb, and storing the current setting in the control record; for example, if the minimum and maximum settings are 0 and 10, and the thumb is in the middle of the scroll bar, 5 is stored as the current setting. The application must then scroll to the corresponding relative position in the document. TrackControl may take additional actions beyond highlighting the control or dragging the indicator, depending on the value passed in the actionProc parameter, as described below. The following tells you what to pass for the standard control types; for a custom control, what you pass will depend on how the control is defined. • If actionProc is NIL, TrackControl performs no additional actions. This is appropriate for simple buttons, check boxes, radio buttons, and the thumb of a scroll bar. • ActionProc may be a pointer to an action procedure that defines some action to be performed repeatedly for as long as the user holds down the mouse button. (See below for details.) • If actionProc is POINTER(–1), TrackControl looks in the control record for a pointer to the control’s default action procedure. If that field of the control record contains a procedure pointer, TrackControl uses the action procedure it points to; if the field contains POINTER (–1), TrackControl calls the control definition function to perform the necessary action. (If the field contains NIL, TrackControl does nothing.) The action procedure in the control definition function is described in the section “Defining Your Own Controls”. The following paragraphs describe only the action procedure whose pointer is passed in the actionProc parameter or stored in the control record. If the mouse button was pressed in an indicator, the action procedure (if any) should have no parameters. This procedure must allow for the fact that the mouse may not be inside the original control part. If the mouse button was pressed in a control part other than an indicator, the action procedure should be of the form PROCEDURE MyAction (theControl: ControlHandle; partCode: INTEGER); In this case, TrackControl passes the control handle and the part code to the action procedure. (It passes 0 in the partCode parameter if the mouse has moved outside the original control part.) As an example of this type of action procedure, consider what should happen when the mouse button is pressed in a scroll arrow or paging region in a scroll bar. For these cases, your action procedure should examine the part code to determine exactly where the mouse button was pressed, scroll up or down a line or page as appropriate, and call SetCtlValue to change the control’s setting and redraw the thumb. Warning: Since it has a different number of parameters depending on whether the mouse button was pressed in an indicator or elsewhere, the action procedure you pass to TrackControl (or whose pointer you store in the control record) can be set up for only one case or the other. If you store a pointer to a default action procedure in a control record, be sure it will be used only when appropriate for that type of action procedure. The only way to specify actions in response to all mouse-down events in a control, regardless of whether they’re in an indicator, is via the control definition function. Assembly-language note: If you store a pointer to a procedure in the global variable DragHook, that procedure will be called repeatedly (with no parameters) for as long as the user holds down the mouse button. TrackControl invokes the Window Manager macro _DragTheRgn, which calls the DragHook procedure. _DragTheRgn uses the pattern stored in the global variable DragPattern for the dragged outline of the indicator. æKY FindControl æFc Controls.h æT Function æTN A96C æD pascal short FindControl(Point thePoint,WindowPtr theWindow,ControlHandle *theControl) = 0xA96C; æDT short myVariable = FindControl((Point) thePoint,(WindowPtr) theWindow,(ControlHandle *) theControl); æMM æRI I-323, P-98, 114, 170 æC When the Window Manager function FindWindow reports that the mouse button was pressed in the content region of a window, and the window contains controls, the application should call FindControl with theWindow equal to the window pointer and thePoint equal to the point where the mouse button was pressed (in the window’s local coordinates). FindControl tells which of the window’s controls, if any, the mouse button was pressed in: • If it was pressed in a visible, active control, FindControl sets the whichControl parameter to the control handle and returns a part code identifying the part of the control that it was pressed in. • If it was pressed in an invisible or inactive control, or not in any control, FindControl sets whichControl to NIL and returns 0 as its result. Warning: Notice that FindControl expects the mouse point in the window’s local coordinates, whereas FindWindow expects it in global coordinates. Always be sure to convert the point to local coordinates with the QuickDraw procedure GlobalToLocal before calling FindControl. Note: FindControl also returns NIL for whichControl and 0 as its result if the window is invisible or doesn’t contain the given point. In these cases, however, FindWindow wouldn’t have returned this window in the first place, so the situation should never arise. æKY SetCtlColor æFc Controls.h æT Function æTN AA43 æD pascal void SetCtlColor(ControlHandle theControl,CCTabHandle newColorTable) = 0xAA43; æDT SetCtlColor((ControlHandle) theControl,(CCTabHandle) newColorTable); æMM æRI V-222 æC [Macintosh II] The SetCtlColor procedure sets or modifies a control’s color table. If the control currently has no auxiliary control record, a new one is created with the given color table and added to the head of the auxiliary control list. If there is already an auxiliary record for the control, its color table is replaced by the contents of newColorTable. If newColorTable has the same contents as the default color table, the control’s existing auxiliary record and color table are removed from the auxiliary control list and deallocated. If theControl = NIL, the operation modifies the default color table itself. If the control is visible, it will be redrawn by SetCtlColor using the new color table. æKY GetAuxCtl æFc Controls.h æT Function æTN AA44 æD pascal Boolean GetAuxCtl(ControlHandle theControl,AuxCtlHandle *acHndl) = 0xAA44; æDT Boolean myVariable = GetAuxCtl((ControlHandle) theControl,(AuxCtlHandle *) acHndl); æMM æRI V-222 æC [Macintosh II] The GetAuxCtl function returns a handle to a control’s AuxCtlRec: • If the given control has its own color table, the function returns TRUE. • If the control used the default color set, the function returns FALSE. • If the control asked to receive the default color set (theControl = NIL), then the function returns TRUE. æKY GetCVariant æFc Controls.h æT Function æTN A809 æD pascal short GetCVariant(ControlHandle theControl) = 0xA809; æDT short myVariable = GetCVariant((ControlHandle) theControl); æRI V-222 æC [Macintosh Plus, Macintosh SE, and Macintosh II] The GetVariant function returns the variant control value for the control described by theControl. This value was formerly stored in the high four bits of the control defproc handle; for future compatibility, use the GetCVariant routine to access this value. æKY dragcontrol æFc Controls.h æT Function æD void dragcontrol(ControlHandle theControl,Point *startPt,const Rect *limitRect, const Rect *slopRect,short axis); æDT dragcontrol((ControlHandle) theControl,(Point *) startPt,(const Rect *) limitRect,( const Rect) * slopRect,(short) axis); æMM æRI I-325 æC Called with the mouse button down inside theControl, DragControl pulls a dotted outline of the control around the screen, following the movements of the mouse until the button is released. When the mouse button is released, DragControl calls MoveControl to move the control to the location to which it was dragged. Note: Before beginning to follow the mouse, DragControl calls the control definition function to allow it to do its own “custom dragging” if it chooses. If the definition function doesn’t choose to do any custom dragging, DragControl uses the default method of dragging described here. The startPt, limitRect, slopRect, and axis parameters have the same meaning as for the Window Manager function DragGrayRgn. These parameters are reviewed briefly below; see the description of DragGrayRgn in the Window Manager chapter for more details. • StartPt is assumed to be the point where the mouse button was originally pressed, in the local coordinates of the control’s window. • LimitRect limits the travel of the control’s outline, and should normally coincide with or be contained within the window’s content region. • SlopRect allows the user some “slop” in moving the mouse; it should completely enclose limitRect. • The axis parameter allows you to constrain the control’s motion to only one axis. It has one of the following values: CONST noConstraint = 0; {no constraint} hAxisOnly = 1; {horizontal axis only} vAxisOnly = 2; {vertical axis only} Assembly-language note: Like TrackControl, DragControl invokes the macro _DragTheRgn, so you can use the global variables DragHook and DragPattern. æKY newcontrol æFc Controls.h æT Function æTN A954 æD ControlHandle newcontrol(WindowPtr theWindow,const Rect *boundsRect,char *title, Boolean visible,short value,short min,short max,short procID,long refCon); æDT ControlHandle myVariable = newcontrol((WindowPtr) theWindow,(const Rect *) boundsRect,(char *) title,() Boolean visible,(short) value,(short) min,(short) max,(short) procID,(long) refCon); æMM æRI I-319, P-112, 114, 177 æC NewControl creates a control, adds it to the beginning of theWindow’s control list, and returns a handle to the new control. The values passed as parameters are stored in the corresponding fields of the control record, as described below. The field that determines highlighting is set to 0 (no highlighting) and the pointer to the default action procedure is set to NIL (none). Note: The control definition function may do additional initialization, including changing any of the fields of the control record. The only standard control for which additional initialization is done is the scroll bar; its control definition function allocates space for a region to hold the thumb and stores the region handle in the contrlData field of the control record. TheWindow is the window the new control will belong to. All coordinates pertaining to the control will be interpreted in this window’s local coordinate system. BoundsRect, given in theWindow’s local coordinates, is the rectangle that encloses the control and thus determines its size and location. Note the following about the enclosing rectangle for the standard controls: • Simple buttons are drawn to fit the rectangle exactly. (The control definition function calls the QuickDraw procedure FrameRoundRect.) To allow for the tallest characters in the system font, there should be at least a 20-point difference between the top and bottom coordinates of the rectangle. • For check boxes and radio buttons, there should be at least a 16-point difference between the top and bottom coordinates. • By convention, scroll bars are 16 pixels wide, so there should be a 16-point difference between the left and right (or top and bottom) coordinates. (If there isn’t, the scroll bar will be scaled to fit the rectangle.) A standard scroll bar should be at least 48 pixels long, to allow room for the scroll arrows and thumb. Title is the control’s title, if any (if none, you can just pass the empty string as the title). Be sure the title will fit in the control’s enclosing rectangle; if it won’t it will be truncated on the right for check boxes and radio buttons, or centered and truncated on both ends for simple buttons. Note: Some non-Roman systems write text from right-to-left, in which case radio buttons and check boxes are drawn with their titles on the left of the control. They are also truncated on the left. See the Script Manager chapter for more information. If the visible parameter is TRUE, NewControl draws the control. Note: It does not use the standard window updating mechanism, but instead draws the control immediately in the window. The min and max parameters define the control’s range of possible settings; the value parameter gives the initial setting. For controls that don’t retain a setting, such as buttons, the values you supply for these parameters will be stored in the control record but will never be used. So it doesn’t matter what values you give for those controls—0 for all three parameters will do. For controls that just retain an on-or-off setting, such as check boxes or radio buttons, min should be 0 (meaning the control is off) and max should be 1 (meaning it’s on). For dials, you can specify whatever values are appropriate for min, max, and value. ProcID is the control definition ID, which leads to the control definition function for this type of control. (The function is read into memory if it isn’t already in memory.) The control definition IDs for the standard control types are listed above under “Controls and Resources”. Control definition IDs for custom control types are discussed later under “Defining Your Own Controls”. RefCon is the control’s reference value, set and used only by your application. æKY findcontrol æFc Controls.h æT Function æD short findcontrol(Point *thePoint,WindowPtr theWindow,ControlHandle *theControl); æDT short myVariable = findcontrol((Point *) thePoint,(WindowPtr) theWindow,(ControlHandle *) theControl); æMM æRI I-323, P-98, 114, 170 æC When the Window Manager function FindWindow reports that the mouse button was pressed in the content region of a window, and the window contains controls, the application should call FindControl with theWindow equal to the window pointer and thePoint equal to the point where the mouse button was pressed (in the window’s local coordinates). FindControl tells which of the window’s controls, if any, the mouse button was pressed in: • If it was pressed in a visible, active control, FindControl sets the whichControl parameter to the control handle and returns a part code identifying the part of the control that it was pressed in. • If it was pressed in an invisible or inactive control, or not in any control, FindControl sets whichControl to NIL and returns 0 as its result. Warning: Notice that FindControl expects the mouse point in the window’s local coordinates, whereas FindWindow expects it in global coordinates. Always be sure to convert the point to local coordinates with the QuickDraw procedure GlobalToLocal before calling FindControl. Note: FindControl also returns NIL for whichControl and 0 as its result if the window is invisible or doesn’t contain the given point. In these cases, however, FindWindow wouldn’t have returned this window in the first place, so the situation should never arise. æKY getctitle æFc Controls.h æT Function æD void getctitle(ControlHandle theControl,char *title); æDT getctitle((ControlHandle) theControl,(char *) title); æRI I-321 æC GetCTitle returns theControl’s title as the value of the title parameter. æKY setctitle æFc Controls.h æT Function æD void setctitle(ControlHandle theControl,char *title); æDT setctitle((ControlHandle) theControl,(char *) title); æMM æRI I-321 æC SetCTitle sets theControl’s title to the given string and redraws the control. æKY trackcontrol æFc Controls.h æT Function æD short trackcontrol(ControlHandle theControl,Point *thePoint,ProcPtr actionProc); æDT short myVariable = trackcontrol((ControlHandle) theControl,(Point *) thePoint,(ProcPtr) actionProc); æMM æRI I-323, P-114, 184 æC When the mouse button is pressed in a visible, active control, the application should call TrackControl with theControl equal to the control handle and startPt equal to the point where the mouse button was pressed (in the local coordinates of the control’s window). TrackControl follows the movements of the mouse and responds in whatever way is appropriate until the mouse button is released; the exact response depends on the type of control and the part of the control in which the mouse button was pressed. If highlighting is appropriate, TrackControl does the highlighting, and undoes it before returning. When the mouse button is released, TrackControl returns with the part code if the mouse is in the same part of the control that it was originally in, or with 0 if not (in which case the application should do nothing). If the mouse button was pressed in an indicator, TrackControl drags a dotted outline of it to follow the mouse. When the mouse button is released, TrackControl calls the control definition function to reposition the control’s indicator. The control definition function for scroll bars responds by redrawing the thumb, calculating the control’s current setting based on the new relative position of the thumb, and storing the current setting in the control record; for example, if the minimum and maximum settings are 0 and 10, and the thumb is in the middle of the scroll bar, 5 is stored as the current setting. The application must then scroll to the corresponding relative position in the document. TrackControl may take additional actions beyond highlighting the control or dragging the indicator, depending on the value passed in the actionProc parameter, as described below. The following tells you what to pass for the standard control types; for a custom control, what you pass will depend on how the control is defined. • If actionProc is NIL, TrackControl performs no additional actions. This is appropriate for simple buttons, check boxes, radio buttons, and the thumb of a scroll bar. • ActionProc may be a pointer to an action procedure that defines some action to be performed repeatedly for as long as the user holds down the mouse button. (See below for details.) • If actionProc is POINTER(–1), TrackControl looks in the control record for a pointer to the control’s default action procedure. If that field of the control record contains a procedure pointer, TrackControl uses the action procedure it points to; if the field contains POINTER (–1), TrackControl calls the control definition function to perform the necessary action. (If the field contains NIL, TrackControl does nothing.) The action procedure in the control definition function is described in the section “Defining Your Own Controls”. The following paragraphs describe only the action procedure whose pointer is passed in the actionProc parameter or stored in the control record. If the mouse button was pressed in an indicator, the action procedure (if any) should have no parameters. This procedure must allow for the fact that the mouse may not be inside the original control part. If the mouse button was pressed in a control part other than an indicator, the action procedure should be of the form PROCEDURE MyAction (theControl: ControlHandle; partCode: INTEGER); In this case, TrackControl passes the control handle and the part code to the action procedure. (It passes 0 in the partCode parameter if the mouse has moved outside the original control part.) As an example of this type of action procedure, consider what should happen when the mouse button is pressed in a scroll arrow or paging region in a scroll bar. For these cases, your action procedure should examine the part code to determine exactly where the mouse button was pressed, scroll up or down a line or page as appropriate, and call SetCtlValue to change the control’s setting and redraw the thumb. Warning: Since it has a different number of parameters depending on whether the mouse button was pressed in an indicator or elsewhere, the action procedure you pass to TrackControl (or whose pointer you store in the control record) can be set up for only one case or the other. If you store a pointer to a default action procedure in a control record, be sure it will be used only when appropriate for that type of action procedure. The only way to specify actions in response to all mouse-down events in a control, regardless of whether they’re in an indicator, is via the control definition function. Assembly-language note: If you store a pointer to a procedure in the global variable DragHook, that procedure will be called repeatedly (with no parameters) for as long as the user holds down the mouse button. TrackControl invokes the Window Manager macro _DragTheRgn, which calls the DragHook procedure. _DragTheRgn uses the pattern stored in the global variable DragPattern for the dragged outline of the indicator. æKY testcontrol æFc Controls.h æT Function æD short testcontrol(ControlHandle theControl,Point *thePt); æDT short myVariable = testcontrol((ControlHandle) theControl,(Point *) thePt); æMM æRI I-325 æC If theControl is visible and active, TestControl tests which part of the control contains thePoint (in the local coordinates of the control’s window); it returns the corresponding part code, or 0 if the point is outside the control. If the control is invisible or inactive, TestControl returns 0. TestControl is called by FindControl and TrackControl; normally you won’t need to call it yourself. æKY CTBUtilities.h æKL AppendDITL CountDITL CTBGetCTBVersion CustomNBP InitCTBUtilities NuLookup NuPLookup ShortenDITL StandardNBP appendDITLBottom appendDITLRight chooseAborted chooseCancel chooseDisaster chooseFailed chooseOKMajor chooseOKMinor CTBUErr ctbuGenericError ctbuNoErr curCTBUVersion DITLMethod hookCancel hookEject hookItemList hookItemRefresh hookKeyBase hookLine hookNull hookOK hookOutline hookPostflight hookPreflight hookReserved1 hookReserved2 hookReserved3 hookReserved4 hookTitle hookVersion hookZoneList hookZoneRefresh hookZoneTitle nameDisable nameFilterProcPtr NameFilterProcPtr nameInclude nameReject NBPReply nlCancel nlEject nlOk NLType NLTypeEntry overlayDITL zoneDisable zoneFilterProcPtr ZoneFilterProcPtr zoneInclude zoneReject æKY curCTBUVersion æFc CTBUtilities.h æT æD curCTBUVersion = 2, æC æKY ctbuGenericError æFc CTBUtilities.h æT æD ctbuGenericError = -1, æC æKY ctbuNoErr æFc CTBUtilities.h æT æD ctbuNoErr = 0, æC æKY overlayDITL æFc CTBUtilities.h æT æD overlayDITL = 0, æC æKY appendDITLRight æFc CTBUtilities.h æT æD appendDITLRight = 1, æC æKY appendDITLBottom æFc CTBUtilities.h æT æD appendDITLBottom = 2, æC æKY chooseDisaster æFc CTBUtilities.h æT æD chooseDisaster = -2, æC æKY chooseFailed æFc CTBUtilities.h æT æD chooseFailed = -1, æC æKY chooseAborted æFc CTBUtilities.h æT æD chooseAborted = 0, æC æKY chooseOKMinor æFc CTBUtilities.h æT æD chooseOKMinor = 1, æC æKY chooseOKMajor æFc CTBUtilities.h æT æD chooseOKMajor = 2, æC æKY chooseCancel æFc CTBUtilities.h æT æD chooseCancel = 3, æC æKY nlOk æFc CTBUtilities.h æT æD nlOk = 0, æC æKY nlCancel æFc CTBUtilities.h æT æD nlCancel = 1, æC æKY nlEject æFc CTBUtilities.h æT æD nlEject = 2, æC æKY nameInclude æFc CTBUtilities.h æT æD nameInclude = 1, æC æKY nameDisable æFc CTBUtilities.h æT æD nameDisable = 2, æC æKY nameReject æFc CTBUtilities.h æT æD nameReject = 3, æC æKY zoneInclude æFc CTBUtilities.h æT æD zoneInclude = 1, æC æKY zoneDisable æFc CTBUtilities.h æT æD zoneDisable = 2, æC æKY zoneReject æFc CTBUtilities.h æT æD zoneReject = 3, æC æKY hookOK æFc CTBUtilities.h æT æD hookOK = 1, æC æKY hookCancel æFc CTBUtilities.h æT æD hookCancel = 2, æC æKY hookOutline æFc CTBUtilities.h æT æD hookOutline = 3, æC æKY hookTitle æFc CTBUtilities.h æT æD hookTitle = 4, æC æKY hookItemList æFc CTBUtilities.h æT æD hookItemList = 5, æC æKY hookZoneTitle æFc CTBUtilities.h æT æD hookZoneTitle = 6, æC æKY hookZoneList æFc CTBUtilities.h æT æD hookZoneList = 7, æC æKY hookLine æFc CTBUtilities.h æT æD hookLine = 8, æC æKY hookVersion æFc CTBUtilities.h æT æD hookVersion = 9, æC æKY hookReserved1 æFc CTBUtilities.h æT æD hookReserved1 = 10, æC æKY hookReserved2 æFc CTBUtilities.h æT æD hookReserved2 = 11, æC æKY hookReserved3 æFc CTBUtilities.h æT æD hookReserved3 = 12, æC æKY hookReserved4 æFc CTBUtilities.h æT æD hookReserved4 = 13, æC æKY hookNull æFc CTBUtilities.h æT æD hookNull = 100, æC æKY hookItemRefresh æFc CTBUtilities.h æT æD hookItemRefresh = 101, æC æKY hookZoneRefresh æFc CTBUtilities.h æT æD hookZoneRefresh = 102, æC æKY hookEject æFc CTBUtilities.h æT æD hookEject = 103, æC æKY hookPreflight æFc CTBUtilities.h æT æD hookPreflight = 104, æC æKY hookPostflight æFc CTBUtilities.h æT æD hookPostflight = 105, æC æKY hookKeyBase æFc CTBUtilities.h æT æD hookKeyBase = 1000, æC æKY CTBUErr æFc CTBUtilities.h æT typedef æD typedef OSErr CTBUErr; æC æKY DITLMethod æFc CTBUtilities.h æT typedef æD typedef short DITLMethod; æC æKY NLTypeEntry æFc CTBUtilities.h æT struct æD struct NLTypeEntry { Handle hIcon; Str32 typeStr; }; typedef struct NLTypeEntry NLTypeEntry; æC æKY NLType æFc CTBUtilities.h æT typedef æD typedef NLTypeEntry NLType[4]; æC æKY NBPReply æFc CTBUtilities.h æT struct æD struct NBPReply { EntityName theEntity; AddrBlock theAddr; }; typedef struct NBPReply NBPReply; æC æKY NameFilterProcPtr æFc CTBUtilities.h æT typedef æD typedef pascal short (*NameFilterProcPtr)(EntityName theEntity); æC æKY ZoneFilterProcPtr æFc CTBUtilities.h æT typedef æD typedef pascal short (*ZoneFilterProcPtr)(Str32 theZone); æC æKY nameFilterProcPtr æFc CTBUtilities.h æT typedef æD typedef NameFilterProcPtr nameFilterProcPtr; æC æKY zoneFilterProcPtr æFc CTBUtilities.h æT typedef æD typedef ZoneFilterProcPtr zoneFilterProcPtr; æC æKY InitCTBUtilities æFc CTBUtilities.h æT Function æD pascal CTBUErr InitCTBUtilities(void); æDT CTBUErr myVariable = InitCTBUtilities()(void); æC æKY CTBGetCTBVersion æFc CTBUtilities.h æT Function æD pascal short CTBGetCTBVersion(void); æDT short myVariable = CTBGetCTBVersion()(void); æC æKY AppendDITL æFc CTBUtilities.h æT Function æD pascal void AppendDITL(DialogPtr theDialog,Handle theDITL,DITLMethod method); æDT AppendDITL((DialogPtr) theDialog,(Handle) theDITL,(DITLMethod) method); æC æKY CountDITL æFc CTBUtilities.h æT Function æD pascal short CountDITL(DialogPtr theDialog); æDT short myVariable = CountDITL((DialogPtr) theDialog); æC æKY ShortenDITL æFc CTBUtilities.h æT Function æD pascal void ShortenDITL(DialogPtr theDialog,short numberItems); æDT ShortenDITL((DialogPtr) theDialog,(short) numberItems); æC æKY NuLookup æFc CTBUtilities.h æT Function æD pascal short NuLookup(Point where,ConstStr255Param prompt,short numTypes, NLType typeList,NameFilterProcPtr nameFilter,ZoneFilterProcPtr zoneFilter, DlgHookProcPtr hookProc,NBPReply *theReply); æDT short myVariable = NuLookup((Point) where,(ConstStr255Param) prompt,(short) numTypes,() NLType typeList,(NameFilterProcPtr) nameFilter,(ZoneFilterProcPtr) zoneFilter,() DlgHookProcPtr hookProc,(NBPReply *) theReply); æC æKY NuPLookup æFc CTBUtilities.h æT Function æD pascal short NuPLookup(Point where,ConstStr255Param prompt,short numTypes, NLType typeList,NameFilterProcPtr nameFilter,ZoneFilterProcPtr zoneFilter, DlgHookProcPtr hookProc,long userData,short dialogID,ModalFilterProcPtr filterProc, NBPReply *theReply); æDT short myVariable = NuPLookup((Point) where,(ConstStr255Param) prompt,(short) numTypes,() NLType typeList,(NameFilterProcPtr) nameFilter,(ZoneFilterProcPtr) zoneFilter,() DlgHookProcPtr hookProc,(long) userData,(short) dialogID,(ModalFilterProcPtr) filterProc,( NBPReply) * theReply); æC æKY StandardNBP æFc CTBUtilities.h æT Function æD pascal short StandardNBP(Point where,ConstStr255Param prompt,short numTypes, NLType typeList,NameFilterProcPtr nameFilter,ZoneFilterProcPtr zoneFilter, DlgHookProcPtr hookProc,NBPReply *theReply); æDT short myVariable = StandardNBP((Point) where,(ConstStr255Param) prompt,(short) numTypes,() NLType typeList,(NameFilterProcPtr) nameFilter,(ZoneFilterProcPtr) zoneFilter,() DlgHookProcPtr hookProc,(NBPReply *) theReply); æC æKY CustomNBP æFc CTBUtilities.h æT Function æD pascal short CustomNBP(Point where,ConstStr255Param prompt,short numTypes, NLType typeList,NameFilterProcPtr nameFilter,ZoneFilterProcPtr zoneFilter, DlgHookProcPtr hookProc,long userData,short dialogID,ModalFilterProcPtr filterProc, NBPReply *theReply); æDT short myVariable = CustomNBP((Point) where,(ConstStr255Param) prompt,(short) numTypes,() NLType typeList,(NameFilterProcPtr) nameFilter,(ZoneFilterProcPtr) zoneFilter,() DlgHookProcPtr hookProc,(long) userData,(short) dialogID,(ModalFilterProcPtr) filterProc,( NBPReply) * theReply); æC æKY Ctype.h æKL _tolower _toupper isalnum isalpha isascii iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit toascii tolower toupper æKY isalpha isupper islower isdigit isxdigit isalnum isspace ispunct isprint isgraph iscntrl isascii æFc CType.h æC These functions tell whether a given character is in one of several categories: alphabetical, uppercase, lowercase, digit, hex digit, white-space, punctuation mark, printing, graphic, or control. A separate function is provided for each category. Synopsis #include <CType.h> int isalpha(int c); int isupper(int c); int islower(int c); int isdigit(int c); int isxdigit(int c); int isalnum(int c); int isspace(int c); int ispunct(int c); int isprint(int c); int isgraph(int c); int iscntrl(int c); int isascii(int c); Description These macros return nonzero for true, zero for false, depending on the corresponding integer value of the given character. The isascii macro is defined on all integer values; the rest are defined only where isascii is true and on the single non-ASCII value EOF(–1). Table 3-1 shows when these macros return the value true. Table 3-1 Character-testing macros Macro Returns true if isascii; c is an ASCII character code lower than128. isalpha; c is a letter [A–Z] or [a–z]. isupper; c is an uppercase letter [A–Z]. islower; c is a lowercase letter [a–z]. isdigit; c is a digit [0–9]. isxdigit; c is a hexadecimal digit [0–9], [A–F], or [a–f]. isalnum; c is alphanumeric (letter or digit). isspace; c is a space, tab, return, new line, vertical tab, or form feed. ispunct; c is a punctuation character (neither control nor alphanumeric). isprint; c is a printing character, space (32) through tilde (126). isgraph; c is a printing character, similar to isprint except false for space. iscntrl; c is a delete character (127) or an ordinary control character (less than 32). Note These macros do not support the Macintosh extended character set. For values outside the domain, the result is undefined. Warning If c is not in the domain of the function, the result is undefined. See also Character case æKY toupper tolower _toupper _tolower toascii æFc CType.h æC The first four of these routines change the case of a character. The toascii function converts any character to an ASCII character. Synopsis #include <CType.h> int toupper(int c); int tolower(int c); int _toupper(int c); int _tolower(int c); int toascii(int c); Description The toupper; and tolower; functions have as their domain the set of ASCII characters (0 through 127) and the constant EOF (– 1). If parameter c to toupper represents a lowercase letter, the result is the corresponding uppercase letter. If parameter c to tolower represents an uppercase letter, the result is the corresponding lowercase letter. All other parameters in the domain are returned unchanged. The _toupper; and _tolower; macros produce the same results as functions toupper and tolower but have restricted domains and are faster. Macro _toupper requires a lowercase letter as its parameter; its result is the corresponding uppercase letter. Macro _tolower requires an uppercase letter as its parameter; its result is the corresponding lowercase letter. Parameters outside the domain cause undefined results. The toascii; macro converts c by clearing all bits that are not part of a standard ASCII character. It is used for compatibility with other systems. Note These routines do not support the Macintosh extended character set (with values greater than 0x7F). For values outside the stated domain, the result is undefined. Warning The _toupper and _tolower macros must be used with care: parameters outside their respective domains cause undefined results. The _toupper macro requires a lowercase letter as its parameter: the _tolower macro requires an uppercase letter as its parameter. See also Character testing æKY isalphaæ æDT int myVariable = isalpha((int) c); æKY isupperæ æDT int myVariable = isupper((int) c); æKY isloweræ æDT int myVariable = islower((int) c); æKY isdigitæ æDT int myVariable = isdigit((int) c); æKY isxdigitæ æDT int myVariable = isxdigit((int) c); æKY isalnumæ æDT int myVariable = isalnum((int) c); æKY isspaceæ æDT int myVariable = isspace((int) c); æKY ispunctæ æDT int myVariable = ispunct((int) c); æKY isprintæ æDT int myVariable = isprint((int) c); æKY isgraphæ æDT int myVariable = isgraph((int) c); æKY iscntrlæ æDT int myVariable = iscntrl((int) c); æKY isasciiæ æDT int my Variable = isascii((int) c); æKY toupperæ æDT int myVariable = toupper((int) c); æKY toloweræ æDT int myVariable = tolower((int) c); æKY _toupperæ æDT int myVariable = _toupper((int) c); æKY _toloweræ æDT int myVariable = _toupper((int) c); æKY toasciiæ æDT int myVariable = toascii((int) c); æKY CursorCtl.h æKL Hide_Cursor InitCursorCtl RotateCursor Show_Cursor SpinCursor acur Acur acurHandle acurPtr ARROW_CURSOR CROSS_CURSOR Cursors HIDDEN_CURSOR I_BEAM_CURSOR PLUS_CURSOR WATCH_CURSOR æKY Acur acur acurPtr acurHandle æFc CursorCtl.h æT struct æD struct Acur { short n; /*Number of cursors ("frames of film")*/ short index; /* Next frame to show <for internal use>*/ short frame1; /*'CURS' resource id for frame #1*/ short fill1; /*<for internal use>*/ short frame2; /*'CURS' resource id for frame #2*/ short fill2; /*<for internal use>*/ short frameN; /*'CURS' resource id for frame #N*/ short fillN; /*<for internal use>*/ }; typedef struct Acur acur,*acurPtr,**acurHandle; æKY Cursors HIDDEN_CURSOR I_BEAM_CURSOR CROSS_CURSOR PLUS_CURSOR WATCH_CURSOR ARROW_CURSOR æFc CursorCtl.h æD enum {HIDDEN_CURSOR,I_BEAM_CURSOR,CROSS_CURSOR,PLUS_CURSOR,WATCH_CURSOR, ARROW_CURSOR}Cursors; typedef unsigned char Cursors; æKY Hide_Cursor æFc CursorCtl.h æT Function æD pascal void Hide_Cursor(void); æDT Hide_Cursor(); æC /* Hide the cursor if it is showing.This is this unit's call to the Mac HideCursor routine.Thus the Mac cursor level is decremented by one when this routine is called. */ æKY InitCursorCtl æFc CursorCtl.h æT Function æD pascal void InitCursorCtl(acurHandle newCursors); æDT InitCursorCtl((acurHandle)newCursors); æC /* Initialize the CursorCtl unit. This should be called once prior to calling RotateCursor or SpinCursor. It need not be called if only Hide_Cursor or Show_Cursor are used. If NewCursors is NULL, InitCursorCtl loads in the 'acur' resource and the 'CURS' resources specified by the 'acur' resource ids. If any of the resources cannot be loaded, the cursor will not be changed. The 'acur' resource is assumed to either be in the currently running tool or application, or the MPW Shell for a tool, or in the System file. The 'acur' resource id must be 0 for a tool or application, 1 for the Shell, and 2 for the System file. If NewCursors is not NULL, it is ASSUMED to be a handle to an 'acur' formatted resource designated by the caller and it will be used instead of doing a GetResource on 'acur'. Note, if RotateCursor or SpinCursor are called without calling InitCursorCtl, then RotateCursor and SpinCursor will do the call for the user the first time it is called. However, the possible disadvantage of using this technique is that the resource memory allocated may have undesirable affect (fragmentation?) on the application. Using InitCursorCtl has the advantage of causing the allocation at a specific time determined by the user. Caution: InitCursorCtl MODIFIES the 'acur' resource in memory. Specifically, it changes each FrameN/fillN integer pair to a handle to the corresponding 'CURS' resource also in memory. Thus if NewCursors is not NULL when InitCursorCtl is called, the caller must guarantee NewCursors always points to a "fresh" copy of an 'acur' resource. This need only be of concern to a caller who wants to repeatly use multiple 'acur' resources during execution of their programs. */ æKY RotateCursor æFc CursorCtl.h æT Function æD pascal void RotateCursor(long counter); æDT RotateCursor((long)counter); æC /* RotateCursor is called to rotate the "I am active" "beach ball" cursor, or to animate whatever sequence of cursors set up by InitCursorCtl. The next cursor ("frame") is used when Counter % 32 = 0 (Counter is some kind of incrementing or decrementing index maintained by the caller). A positive counter sequences forward through the cursors (e.g., it rotates the "beach ball" cursor clockwise), and a negative cursor sequences through the cursors backwards (e.g., it rotates the "beach ball" cursor counterclockwise). Note, RotateCursor just does a Mac SetCursor call for the proper cursor picture. It is assumed the cursor is visible from a prior Show_Cursor call. */ æKY Show_Cursor æFc CursorCtl.h æT Function æD pascal void Show_Cursor(Cursors cursorKind); æDT Show_Cursor((Cursors)cursorKind); æC /* Increment the cursor level, which may have been decremented by Hide_Cursor, and display the specified cursor if the level becomes 0 (it is never incremented beyond 0).The CursorKind is the kind of cursor to show. It is one of the values HIDDEN_CURSOR, I_BEAM_CURSOR, CROSS_CURSOR, PLUS_CURSOR, WATCH_CURSOR, and ARROW_CURSOR. Except for HIDDEN_CURSOR, a Mac SetCursor is done for the specified cursor prior to doing a ShowCursor. HIDDEN_CURSOR just causes a ShowCursor call. Note, ARROW_CURSOR will only work correctly if there is already a grafPort set up pointed to by 0(A5). */ æKY SpinCursor æFc CursorCtl.h æT Function æD pascal void SpinCursor(short increment); æDT SpinCursor((short)increment); æC /* SpinCursor is similar in function to RotateCursor, except that instead of passing a counter, an Increment is passed an added to a counter maintained here. SpinCursor is provided for those users who do not happen to have a convenient counter handy but still want to use the spinning "beach ball" cursor, or any sequence of cursors set up by InitCursorCtl. A positive increment sequences forward through the curos (rotating the "beach ball" cursor clockwise), and a negative increment sequences backward through the cursors (rotating the "beach ball" cursor counter-clockwise). A zero value for the increment resets the counter to zero. Note, it is the increment, and not the value of the counter that determines the sequencing direction of the cursor (and hence the spin direction of the "beach ball" cursor). */ æKY DatabaseAccess.h æKL DBBreak DBDisposeQuery DBEnd DBExec DBGetConnInfo DBGetErr DBGetItem DBGetNewQuery DBGetQueryResults DBGetResultHandler DBGetSessionNum DBInit DBInstallResultHandler DBKill DBRemoveResultHandler DBResultsToText DBSend DBSendItem DBStartQuery DBState DBUnGetItem InitDBPack ColInfoArray ColInfoHandle ColInfoPtr ColTypesArray ColTypesHandle ColTypesPtr DBAsyncParamBlockRec DBAsyncParmBlkPtr DBColInfoRecord DBType kDBAboutToInit kDBExecComplete kDBGetItemComplete kDBGetQueryResultsComplete kDBInitComplete kDBLastColFlag kDBNullFlag kDBSendComplete kDBStartQueryComplete kDBUpdateWind kDBWaitForever QueryArray QueryHandle QueryListHandle QueryListPtr QueryPtr QueryRecord rcDBAsyncNotSupp rcDBBadAsyncPB rcDBBadDDEV rcDBBadSessID rcDBBadSessNum rcDBBadType rcDBBreak rcDBError rcDBExec rcDBNoHandler rcDBNull rcDBPackNotInited rcDBValue rcDBWrongVersion ResListElem ResListHandle ResListPtr ResultsRecord typeAnyType typeColBreak typeDate typeDecimal typeDiscard typeLBin typeLChar typeMoney typeNone typeRowBreak typeTime typeTimeStamp typeUnknown typeVBin typeVChar æKY rcDBNull æFc DatabaseAccess.h æT æD rcDBNull = -800, æC æKY rcDBValue æFc DatabaseAccess.h æT æD rcDBValue = -801, æC æKY rcDBError æFc DatabaseAccess.h æT æD rcDBError = -802, æC æKY rcDBBadType æFc DatabaseAccess.h æT æD rcDBBadType = -803, æC æKY rcDBBreak æFc DatabaseAccess.h æT æD rcDBBreak = -804, æC æKY rcDBExec æFc DatabaseAccess.h æT æD rcDBExec = -805, æC æKY rcDBBadSessID æFc DatabaseAccess.h æT æD rcDBBadSessID = -806, æC æKY rcDBBadSessNum æFc DatabaseAccess.h æT æD rcDBBadSessNum = -807, /* bad session number for DBGetConnInfo */ æC æKY rcDBBadDDEV æFc DatabaseAccess.h æT æD rcDBBadDDEV = -808, /* bad ddev specified on DBInit */ æC æKY rcDBAsyncNotSupp æFc DatabaseAccess.h æT æD rcDBAsyncNotSupp = -809, /* ddev does not support async calls */ æC æKY rcDBBadAsyncPB æFc DatabaseAccess.h æT æD rcDBBadAsyncPB = -810, /* tried to kill a bad pb */ æC æKY rcDBNoHandler æFc DatabaseAccess.h æT æD rcDBNoHandler = -811, /* no app handler for specified data type */ æC æKY rcDBWrongVersion æFc DatabaseAccess.h æT æD rcDBWrongVersion = -812, /* incompatible versions */ æC æKY rcDBPackNotInited æFc DatabaseAccess.h æT æD rcDBPackNotInited = -813, /* attempt to call other routine before InitDBPack */ æC æKY kDBUpdateWind æFc DatabaseAccess.h æT æD kDBUpdateWind = 0, æC æKY kDBAboutToInit æFc DatabaseAccess.h æT æD kDBAboutToInit = 1, æC æKY kDBInitComplete æFc DatabaseAccess.h æT æD kDBInitComplete = 2, æC æKY kDBSendComplete æFc DatabaseAccess.h æT æD kDBSendComplete = 3, æC æKY kDBExecComplete æFc DatabaseAccess.h æT æD kDBExecComplete = 4, æC æKY kDBStartQueryComplete æFc DatabaseAccess.h æT æD kDBStartQueryComplete = 5, æC æKY kDBGetItemComplete æFc DatabaseAccess.h æT æD kDBGetItemComplete = 6, æC æKY kDBGetQueryResultsComplete æFc DatabaseAccess.h æT æD kDBGetQueryResultsComplete = 7, æC æKY typeNone æFc DatabaseAccess.h æT #define æD #define typeNone 'none' æC æKY typeDate æFc DatabaseAccess.h æT #define æD #define typeDate 'date' æC æKY typeTime æFc DatabaseAccess.h æT #define æD #define typeTime 'time' æC æKY typeTimeStamp æFc DatabaseAccess.h æT #define æD #define typeTimeStamp 'tims' æC æKY typeDecimal æFc DatabaseAccess.h æT #define æD #define typeDecimal 'deci' æC æKY typeMoney æFc DatabaseAccess.h æT #define æD #define typeMoney 'mone' æC æKY typeVChar æFc DatabaseAccess.h æT #define æD #define typeVChar 'vcha' æC æKY typeVBin æFc DatabaseAccess.h æT #define æD #define typeVBin 'vbin' æC æKY typeLChar æFc DatabaseAccess.h æT #define æD #define typeLChar 'lcha' æC æKY typeLBin æFc DatabaseAccess.h æT #define æD #define typeLBin 'lbin' æC æKY typeDiscard æFc DatabaseAccess.h æT #define æD #define typeDiscard 'disc' æC æKY typeUnknown æFc DatabaseAccess.h æT #define æD #define typeUnknown 'unkn' æC æKY typeColBreak æFc DatabaseAccess.h æT #define æD #define typeColBreak 'colb' æC æKY typeRowBreak æFc DatabaseAccess.h æT #define æD #define typeRowBreak 'rowb' æC æKY typeAnyType æFc DatabaseAccess.h æT #define æD #define typeAnyType (DBType)0 æC æKY kDBWaitForever æFc DatabaseAccess.h æT æD kDBWaitForever = -1, æC æKY kDBLastColFlag æFc DatabaseAccess.h æT æD kDBLastColFlag = 0x0001, æC æKY kDBNullFlag æFc DatabaseAccess.h æT æD kDBNullFlag = 0x0004, æC æKY DBType æFc DatabaseAccess.h æT typedef æD typedef OSType DBType; æC æKY DBAsyncParamBlockRec DBAsyncParmBlkPtr æFc DatabaseAccess.h æT struct æD struct DBAsyncParamBlockRec { ProcPtr completionProc; /* pointer to completion routine */ OSErr result; /* result of call */ long userRef; /* for application's use */ long ddevRef; /* for ddev's use */ long reserved; /* for internal use */ }; typedef struct DBAsyncParamBlockRec DBAsyncParamBlockRec; typedef DBAsyncParamBlockRec *DBAsyncParmBlkPtr; æC æKY ResListElem ResListPtr ResListHandle æFc DatabaseAccess.h æT struct æD struct ResListElem { ResType theType; /* resource type */ short id; /* resource id */ }; typedef struct ResListElem ResListElem; typedef ResListElem *ResListPtr, **ResListHandle; æC æKY QueryArray QueryListPtr QueryListHandle æFc DatabaseAccess.h æT struct æD typedef Handle **QueryListHandle; æC æKY QueryRecord QueryPtr QueryHandle æFc DatabaseAccess.h æT struct æD struct QueryRecord { short version; /* version */ short id; /* id of 'qrsc' this came from */ Handle queryProc; /* handle to query def proc */ Str63 ddevName; /* ddev name */ Str255 host; /* host name */ Str255 user; /* user name */ Str255 password; /* password */ Str255 connStr; /* connection string */ short currQuery; /* index of current query */ short numQueries; /* number of queries in list */ QueryListHandle queryList; /* handle to array of handles to text */ short numRes; /* number of resources in list */ ResListHandle resList; /* handle to array of resource list elements */ Handle dataHandle; /* for use by query def proc */ long refCon; /* for use by application */ }; typedef struct QueryRecord QueryRecord; typedef QueryRecord *QueryPtr, **QueryHandle; æC æKY ColTypesArray ColTypesPtr ColTypesHandle æFc DatabaseAccess.h æT struct æD typedef Handle ColTypesHandle; æC æKY DBColInfoRecord æFc DatabaseAccess.h æT struct æD struct DBColInfoRecord { short len; short places; short flags; }; typedef struct DBColInfoRecord DBColInfoRecord; æC æKY ColInfoArray ColInfoPtr ColInfoHandle æFc DatabaseAccess.h æT struct æD typedef Handle ColInfoHandle; æC æKY ResultsRecord æFc DatabaseAccess.h æT struct æD struct ResultsRecord { short numRows; /* number of rows in result */ short numCols; /* number of columns per row */ ColTypesHandle colTypes; /* data type array */ Handle colData; /* actual results */ ColInfoHandle colInfo; /* DBColInfoRecord array */ }; typedef struct ResultsRecord ResultsRecord; æC æKY InitDBPack æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr InitDBPack(void) = {0x3F3C,0x0004,0x303C,0x0100,0xA82F}; æDT OSErr myVariable = InitDBPack()(void); æC æKY DBInit æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBInit(long *sessID,ConstStr63Param ddevName,ConstStr255Param host, ConstStr255Param user,ConstStr255Param passwd,ConstStr255Param connStr, DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0E02,0xA82F}; æDT OSErr myVariable = DBInit((long *) sessID,(ConstStr63Param) ddevName,(ConstStr255Param) host,() ConstStr255Param user,(ConstStr255Param) passwd,(ConstStr255Param) connStr,() DBAsyncParmBlkPtr asyncPB); æC æKY DBEnd æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBEnd(long sessID,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0403,0xA82F}; æDT OSErr myVariable = DBEnd((long) sessID,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBGetConnInfo æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetConnInfo(long sessID,short sessNum,long *returnedID,long *version, Str63 ddevName,Str255 host,Str255 user,Str255 network,Str255 connStr,long *start, OSErr *state,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x1704,0xA82F}; æDT OSErr myVariable = DBGetConnInfo((long) sessID,(short) sessNum,(long *) returnedID,(long *) version,() Str63 ddevName,(Str255) host,(Str255) user,(Str255) network,(Str255) connStr,(long *) start,( OSErr) * state,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBGetSessionNum æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetSessionNum(long sessID,short *sessNum,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0605,0xA82F}; æDT OSErr myVariable = DBGetSessionNum((long) sessID,(short *) sessNum,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBSend æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBSend(long sessID,char *text,short len,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0706,0xA82F}; æDT OSErr myVariable = DBSend((long) sessID,(char *) text,(short) len,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBSendItem æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBSendItem(long sessID,DBType dataType,short len,short places, short flags,void *buffer,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0B07,0xA82F}; æDT OSErr myVariable = DBSendItem((long) sessID,(DBType) dataType,(short) len,(short) places,() short flags,(void *) buffer,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBExec æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBExec(long sessID,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0408,0xA82F}; æDT OSErr myVariable = DBExec((long) sessID,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBState æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBState(long sessID,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0409,0xA82F}; æDT OSErr myVariable = DBState((long) sessID,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBGetErr æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetErr(long sessID,long *err1,long *err2,Str255 item1,Str255 item2, Str255 errorMsg,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0E0A,0xA82F}; æDT OSErr myVariable = DBGetErr((long) sessID,(long *) err1,(long *) err2,(Str255) item1,(Str255) item2,() Str255 errorMsg,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBBreak æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBBreak(long sessID,Boolean abort,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x050B,0xA82F}; æDT OSErr myVariable = DBBreak((long) sessID,(Boolean) abort,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBGetItem æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetItem(long sessID,long timeout,DBType *dataType,short *len, short *places,short *flags,void *buffer,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x100C,0xA82F}; æDT OSErr myVariable = DBGetItem((long) sessID,(long) timeout,(DBType *) dataType,(short *) len,( short) * places,(short *) flags,(void *) buffer,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBUnGetItem æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBUnGetItem(long sessID,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x040D,0xA82F}; æDT OSErr myVariable = DBUnGetItem((long) sessID,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBKill æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBKill(DBAsyncParmBlkPtr asyncPB) = {0x303C,0x020E,0xA82F}; æDT OSErr myVariable = DBKill((DBAsyncParmBlkPtr) asyncPB); æC æKY DBGetNewQuery æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetNewQuery(short queryID,QueryHandle *query) = {0x303C,0x030F,0xA82F}; æDT OSErr myVariable = DBGetNewQuery((short) queryID,(QueryHandle *) query); æC æKY DBDisposeQuery æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBDisposeQuery(QueryHandle query) = {0x303C,0x0210,0xA82F}; æDT OSErr myVariable = DBDisposeQuery((QueryHandle) query); æC æKY DBStartQuery æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBStartQuery(long *sessID,QueryHandle query,ProcPtr statusProc, DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0811,0xA82F}; æDT OSErr myVariable = DBStartQuery((long *) sessID,(QueryHandle) query,(ProcPtr) statusProc,() DBAsyncParmBlkPtr asyncPB); æC æKY DBGetQueryResults æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetQueryResults(long sessID,ResultsRecord *results,long timeout, ProcPtr statusProc,DBAsyncParmBlkPtr asyncPB) = {0x303C,0x0A12,0xA82F}; æDT OSErr myVariable = DBGetQueryResults((long) sessID,(ResultsRecord *) results,(long) timeout,() ProcPtr statusProc,(DBAsyncParmBlkPtr) asyncPB); æC æKY DBResultsToText æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBResultsToText(ResultsRecord *results,Handle *theText) = {0x303C,0x0413,0xA82F}; æDT OSErr myVariable = DBResultsToText((ResultsRecord *) results,(Handle *) theText); æC æKY DBInstallResultHandler æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBInstallResultHandler(DBType dataType,ProcPtr theHandler, Boolean isSysHandler) = {0x303C,0x0514,0xA82F}; æDT OSErr myVariable = DBInstallResultHandler((DBType) dataType,(ProcPtr) theHandler,() Boolean isSysHandler); æC æKY DBRemoveResultHandler æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBRemoveResultHandler(DBType dataType) = {0x303C,0x0215,0xA82F}; æDT OSErr myVariable = DBRemoveResultHandler((DBType) dataType); æC æKY DBGetResultHandler æFc DatabaseAccess.h æT Function æTN A82F æD pascal OSErr DBGetResultHandler(DBType dataType,ProcPtr *theHandler,Boolean getSysHandler) = {0x303C,0x0516,0xA82F}; æDT OSErr myVariable = DBGetResultHandler((DBType) dataType,(ProcPtr *) theHandler,(Boolean) getSysHandler); æC æKY Desk.h æKL CloseDeskAcc opendeskacc OpenDeskAcc SystemClick SystemEdit SystemEvent SystemMenu SystemTask accClear accCopy accCursor accCut accEvent accMenu accPaste accRun accUndo goodbye æKY accEvent æFc Desk.h æT æD accEvent = 64, æC æKY accRun æFc Desk.h æT æD accRun = 65, æC æKY accCursor æFc Desk.h æT æD accCursor = 66, æC æKY accMenu æFc Desk.h æT æD accMenu = 67, æC æKY accUndo æFc Desk.h æT æD accUndo = 68, æC æKY accCut æFc Desk.h æT æD accCut = 70, æC æKY accCopy æFc Desk.h æT æD accCopy = 71, æC æKY accPaste æFc Desk.h æT æD accPaste = 72, æC æKY accClear æFc Desk.h æT æD accClear = 73, æC æKY goodbye æFc Desk.h æT æD goodbye = -1, /*goodbye message*/ æC æKY OpenDeskAcc æFc Desk.h æT Function æTN A9B6 æD pascal short OpenDeskAcc(ConstStr255Param deskAccName) = 0xA9B6; æDT short myVariable = OpenDeskAcc((ConstStr255Param) deskAccName); æMM æRI I-440 æC OpenDeskAcc opens the desk accessory having the given name and displays its window (if any) as the active window. The name is the accessory’s resource name, which you get from the Apple menu by calling the Menu Manager procedure GetItem. OpenDeskAcc calls the Resource Manager to read the desk accessory from the resource file into the application heap. You should ignore the value returned by OpenDeskAcc. If the desk accessory is successfully opened, the function result is its driver reference number. However, if the desk accessory can’t be opened, the function result is undefined; the accessory will have taken care of informing the user of the problem (such as memory full) and won’t display itself. Warning: Early versions of some desk accessories may set the current grafPort to the accessory’s port upon return from OpenDeskAcc. To be safe, you should bracket your call to OpenDeskAcc with calls to the QuickDraw procedures GetPort and SetPort, to save and restore the current port. Note: Programmers concerned about the amount of available memory should be aware that an open desk accessory uses from 1K to 3K bytes of heap space in addition to the space needed for the accessory itself. The desk accessory is responsible for determining whether there is sufficient memory for it to run; this can be done by calling SizeResource followed by ResrvMem. æKY CloseDeskAcc æFc Desk.h æT Function æTN A9B7 æD pascal void CloseDeskAcc(short refNum) = 0xA9B7; æDT CloseDeskAcc((short) refNum); æRI I-440 æC When a system window is active and the user chooses Close from the File menu, call CloseDeskAcc to close the desk accessory. RefNum is the driver reference number for the desk accessory, which you get from the windowKind field of its window. The Desk Manager automatically closes a desk accessory if the user clicks its close box. Also, since the application heap is released when the application terminates, every desk accessory goes away at that time. æKY SystemClick æFc Desk.h æT Function æTN A9B3 æD pascal void SystemClick(const EventRecord *theEvent,WindowPtr theWindow) = 0xA9B3; æDT SystemClick((const EventRecord *) theEvent,(WindowPtr) theWindow); æMM æRI I-441, P-35, 182 æC When a mouse-down event occurs and the Window Manager function FindWindow reports that the mouse button was pressed in a system window, the application should call SystemClick with the event record and the window pointer. If the given window belongs to a desk accessory, SystemClick sees that the event gets handled properly. SystemClick determines which part of the desk accessory’s window the mouse button was pressed in, and responds accordingly (similar to the way your application responds to mouse activities in its own windows). • If the mouse button was pressed in the content region of the window and the window was active, SystemClick sends the mouse-down event to the desk accessory, which processes it as appropriate. • If the mouse button was pressed in the content region and the window was inactive, SystemClick makes it the active window. • If the mouse button was pressed in the drag region, SystemClick calls the Window Manager procedure DragWindow to pull an outline of the window across the screen and move the window to a new location. If the window was inactive, DragWindow also makes it the active window (unless the Command key was pressed along with the mouse button). • If the mouse button was pressed in the go-away region, SystemClick calls the Window Manager function TrackGoAway to determine whether the mouse is still inside the go-away region when the click is completed: If so, it tells the desk accessory to close itself; otherwise, it does nothing. æKY SystemEdit æFc Desk.h æT Function æTN A9C2 æD pascal Boolean SystemEdit(short editCmd) = 0xA9C2; æDT Boolean myVariable = SystemEdit((short) editCmd); æMM æRT 180, 215 æRI I-441 æC Assembly-language note: The macro you invoke to call SystemEdit from assembly language is named _SysEdit. Call SystemEdit when there’s a mouse-down event in the menu bar and the user chooses one of the five standard editing commands from the Edit menu. Pass one of the following as the value of the editCmd parameter: editCmd Editing command 0 Undo 2 Cut 3 Copy 4 Paste 5 Clear If your Edit menu contains these five commands in the standard arrangement (the order listed above, with a dividing line between Undo and Cut), you can simply call SystemEdit(menuItem-1) where menuItem is the menu item number. If the active window doesn’t belong to a desk accessory, SystemEdit returns FALSE; the application should then process the editing command as usual. If the active window does belong to a desk accessory, SystemEdit asks that accessory to process the command and returns TRUE; in this case, the application should ignore the command. Note: It’s up to the application to make sure desk accessories get their editing commands that are chosen from the Edit menu. In particular, make sure your application hasn’t disabled the Edit menu or any of the five standard commands when a desk accessory is activated. æKY SystemTask æFc Desk.h æT Function æTN A9B4 æD pascal void SystemTask(void) = 0xA9B4; æDT SystemTask()(void); æRT 85 æRI I-442, 444, II-189, N85-1 æC For each open desk accessory (or other device driver performing periodic actions), SystemTask causes the accessory to perform the periodic action defined for it, if any such action has been defined and if the proper time period has passed since the action was last performed. For example, a clock accessory can be defined such that the second hand is to move once every second; the periodic action for the accessory will be to move the second hand to the next position, and SystemTask will alert the accessory every second to perform that action. You should call SystemTask as often as possible, usually once every time through your main event loop. Call it more than once if your application does an unusually large amount of processing each time through the loop. Note: SystemTask should be called at least every sixtieth of a second. æKY SystemEvent æFc Desk.h æT Function æTN A9B2 æD pascal Boolean SystemEvent(const EventRecord *theEvent) = 0xA9B2; æDT Boolean myVariable = SystemEvent((const EventRecord *) theEvent); æRT 5,85 æRI I-442, N5-1, N85-1 æC SystemEvent is called only by the Toolbox Event Manager function GetNextEvent when it receives an event, to determine whether the event should be handled by the application or by the system. If the given event should be handled by the application, SystemEvent returns FALSE; otherwise, it calls the appropriate system code to handle the event and returns TRUE. In the case of a null or mouse-down event, SystemEvent does nothing but return FALSE. Notice that it responds this way to a mouse-down event even though the event may in fact have occurred in a system window (and therefore may have to be handled by the system). The reason for this is that the check for exactly where the event occurred (via the Window Manager function FindWindow) is made later by the application and so would be made twice if SystemEvent were also to do it. To avoid this duplication, SystemEvent passes the event on to the application and lets it make the sole call to FindWindow. Should FindWindow reveal that the mouse-down event did occur in a system window, the application can then call SystemClick, as described above, to get the system to handle it. If the given event is a mouse-up or any keyboard event (including keyboard equivalents of commands), SystemEvent checks whether the active window belongs to a desk accessory and whether that accessory can handle this type of event. If so, it sends the event to the desk accessory and returns TRUE; otherwise, it returns FALSE. If SystemEvent is passed an activate or update event, it checks whether the window the event occurred in is a system window belonging to a desk accessory and whether that accessory can handle this type of event. If so, it sends the event to the desk accessory and returns TRUE; otherwise, it returns FALSE. Note: It’s unlikely that a desk accessory would not be set up to handle keyboard, activate, and update events, or that it would handle mouse-up events. If the given event is a disk-inserted event, SystemEvent does some low-level processing (by calling the File Manager function MountVol) but passes the event on to the application by returning FALSE, in case the application wants to do further processing. Finally, SystemEvent returns FALSE for network, device driver, and application-defined events. Assembly-language note: Advanced programmers can make SystemEvent always return FALSE by setting the global variable SEvtEnb (a byte) to 0. æKY SystemMenu æFc Desk.h æT Function æTN A9B5 æD pascal void SystemMenu(long menuResult) = 0xA9B5; æDT SystemMenu((long) menuResult); æMM æRI I-443 æC SystemMenu is called only by the Menu Manager functions MenuSelect and MenuKey, when an item in a menu belonging to a desk accessory has been chosen. The menuResult parameter has the same format as the value returned by MenuSelect and MenuKey: the menu ID in the high-order word and the menu item number in the low-order word. (The menu ID will be negative.) SystemMenu directs the desk accessory to perform the appropriate action for the given menu item. æKY opendeskacc æFc Desk.h æT Function æD short opendeskacc(char *deskAccName); æDT short myVariable = opendeskacc((char *) deskAccName); æMM æRI I-440 æC OpenDeskAcc opens the desk accessory having the given name and displays its window (if any) as the active window. The name is the accessory’s resource name, which you get from the Apple menu by calling the Menu Manager procedure GetItem. OpenDeskAcc calls the Resource Manager to read the desk accessory from the resource file into the application heap. You should ignore the value returned by OpenDeskAcc. If the desk accessory is successfully opened, the function result is its driver reference number. However, if the desk accessory can’t be opened, the function result is undefined; the accessory will have taken care of informing the user of the problem (such as memory full) and won’t display itself. Warning: Early versions of some desk accessories may set the current grafPort to the accessory’s port upon return from OpenDeskAcc. To be safe, you should bracket your call to OpenDeskAcc with calls to the QuickDraw procedures GetPort and SetPort, to save and restore the current port. Note: Programmers concerned about the amount of available memory should be aware that an open desk accessory uses from 1K to 3K bytes of heap space in addition to the space needed for the accessory itself. The desk accessory is responsible for determining whether there is sufficient memory for it to run; this can be done by calling SizeResource followed by ResrvMem. æKY DeskBus.h æKL ADBOp ADBReInit CountADBs GetADBInfo GetIndADB SetADBInfo ADBAddress ADBDataBlock ADBDBlkPtr ADBOpBlock ADBOpBPtr ADBSetInfoBlock ADBSInfoPtr æKY ADBAddress æFc DeskBus.h æT typedef æD typedef char ADBAddress; æC æKY ADBOpBlock ADBOpBPtr æFc DeskBus.h æT struct æD struct ADBOpBlock { Ptr dataBuffPtr; /*address of data buffer*/ Ptr opServiceRtPtr; /*service routine pointer*/ Ptr opDataAreaPtr; /*optional data area address*/ }; typedef struct ADBOpBlock ADBOpBlock; typedef ADBOpBlock *ADBOpBPtr; æC æKY ADBDataBlock ADBDBlkPtr æFc DeskBus.h æT struct æD struct ADBDataBlock { char devType; /*device type*/ char origADBAddr; /*original ADB Address*/ Ptr dbServiceRtPtr; /*service routine pointer*/ Ptr dbDataAreaAddr; /*data area address*/ }; typedef struct ADBDataBlock ADBDataBlock; typedef ADBDataBlock *ADBDBlkPtr; æC æKY ADBSetInfoBlock ADBSInfoPtr æFc DeskBus.h æT struct æD struct ADBSetInfoBlock { Ptr siServiceRtPtr; /*service routine pointer*/ Ptr siDataAreaAddr; /*data area address*/ }; typedef struct ADBSetInfoBlock ADBSetInfoBlock; typedef ADBSetInfoBlock *ADBSInfoPtr; æC æKY ADBReInit æFc DeskBus.h æT Function æTN A07B æD pascal void ADBReInit(void) = 0xA07B; æDT ADBReInit()(void); æMM æRT 143, 206 æRI V-367, N143 æC Trap macro _ADBReInit ADBReInit reinitializes the entire Apple Desktop Bus. It clears the ADB device table to zeros and places a SendReset command on the bus to reset all devices to their original addresses. ADBReInit has no parameters. Because it does not deallocate ADB resources on the system heap, ADBReInit should not be used for routine bus initialization. Apple strongly recommends against adding devices while the system is running; therefore, you should never call ADBReInit. ADBReInit also calls a routine pointed to by the low memory global JADBProc at the beginning and end of its execution. You can insert your own preprocessing/postprocessing routine by changing the value of JADBProc; ADBReInit conditions it by setting D0 to 0 for preprocessing and to 1 for postprocessing. Your procedure must restore the value of D0 and branch to the original value of JADBProc on exit. JADBProc should be used to de-allocate memory used by the driver (see MacDTS Sample Code “TbltDrvr” for an example), and then it should chain to the procedure originally found in JADBProc. The complete ADBReInit sequence is therefore the following: • JSR to JADBProc with D0 set to 0 • reinitialize the Apple Desktop Bus • clear the ADB device table • JSR to JADBProc with D0 set to 1 æKY ADBOp æFc DeskBus.h æT Function æD pascal OSErr ADBOp(Ptr data,ProcPtr compRout,Ptr buffer,short commandNum); æDT OSErr myVariable = ADBOp((Ptr) data,(ProcPtr) compRout,(Ptr) buffer,(short) commandNum); æRT 206 æRI V-368 æC Trap macro _ADBOp On entry: A0: pointer to parameter block D0: commandNum (byte) Parameter block --> 0 buffer pointer --> 4 compRout pointer --> 8 data pointer On exit: D0: result code (byte) The completion routine pointed to by compRout will be passed the following parameters on entry: D0: commandNum (byte) A0: pointer to buffer, data stored as a Pascal string (maximum 8 bytes data preceded by one length byte) A1: pointer to completion routine (compRout) A2: pointer to optional data area (data) ADBOp transmits over the bus the command byte whose value is given by commandNum. The structure of the command byte is given earlier in Figure 1. ADBOp executes only when the ADB is otherwise idle; otherwise it is held in a command queue. It returns an error if the command queue is full. The length of the data buffer pointed to by buffer is contained in its first byte, like a Pascal string. The optional data area pointed to by data is for local storage by the completion routine pointed to by compRout. ADBop should be used sparingly; it is not intended for polling a device. The host automatically polls devices with data to deliver. Result codes noErr No error –1 Unsuccessful completion æKY CountADBs æFc DeskBus.h æT Function æTN A077 æD #pragma parameter __D0 CountADBs pascal short CountADBs(void) = 0xA077; æDT #pragma parameter __D0 CountADBs pascal short myVariable = CountADBs()(void); æRT 206 æRI V-369 æC Trap macro _CountADBs On exit: D0: number of devices (byte) CountADBs returns a value representing the number of devices connected to the ADB by counting the number of entries in the device table. It has no arguments and returns no error codes. æKY GetIndADB æFc DeskBus.h æT Function æTN A078 æD #pragma parameter __D0 GetIndADB(__A0,__D0) pascal ADBAddress GetIndADB(ADBDataBlock *info,short devTableIndex) = 0xA078; æDT #pragma parameter __D0 myVariable = GetIndADB()(__A0,)(__D0); æRT 206 æRI V-369 æC Trap macro _GetIndADB On entry: A0: pointer to parameter block D0: entry index number; range = 1..CountADBs (byte) Parameter block <-- 0 device type byte (handler ID) <-- 1 original ADB address byte <-- 2 service routine address pointer (compRout) <-- 6 data area address pointer (data) On exit: D0: positive value: current ADB address (byte) negative value: error code (byte) GetIndADB returns information from the ADB device table entry whose index number is given by devTableIndex. ADBDataBlock has this form: TYPE ADBDataBlock = PACKED RECORD devType: SignedByte; {device type (handler ID)} origADBAddr: SignedByte; {original ADB address} dbServiceRtPtr: Ptr; {service routine address (compRout)} dbDataAreaAddr: Ptr {data area address (data)} END; GetIndADB returns the current ADB address of the device. If it is unable to complete execution successfully, GetIndADB returns a negative value. æKY GetADBInfo æFc DeskBus.h æT Function æTN A079 æD #pragma parameter __D0 GetADBInfo(__A0,__D0) pascal OSErr GetADBInfo(ADBDataBlock *info,ADBAddress adbAddr) = 0xA079; æDT #pragma parameter __D0 myVariable = GetADBInfo()(__A0,)(__D0); æRI V-370 æC Trap macro _GetADBInfo On entry: A0: pointer to parameter block D0: ADB address of the device (byte) Parameter block <-- 0 device handler ID byte <-- 1 original ADB address byte <-- 2 service routine address pointer (compRout) <-- 6 data area address pointer (data) On exit: D0: result code (byte) GetADBInfo returns information from the ADB device table entry of the device whose ADB address is given by ABDAddr. The structure of ADBDataBlock is given above under “GetIndADB”. Result codes noErr No error æKY SetADBInfo æFc DeskBus.h æT Function æTN A07A æD #pragma parameter __D0 SetADBInfo(__A0,__D0) pascal OSErr SetADBInfo(ADBSetInfoBlock *info,ADBAddress adbAddr) = 0xA07A; æDT #pragma parameter __D0 myVariable = SetADBInfo()(__A0,)(__D0); æRT 206 æRI V-370 æC Trap macro _SetADBInfo On entry: A0: pointer to parameter block D0: ADB address of the device (byte) Parameter block --> 0 service routine address pointer (compRout) --> 4 data area address pointer (data) On exit: D0: result code (byte) SetADBInfo sets the service routine address and the data area address in the ADB device table entry for the device whose ADB address is given by ABDAddr. ADBSetInfoBlock has this form: TYPE ADBSetInfoBlock = RECORD siServiceRtPtr: Ptr; {service routine address (compRout)} siDataAreaAddr: Ptr {data area address (data)} END; Result codes noErr No error Warning: You should send a Flush command to the device after calling it with SetADBInfo, to prevent it sending old data to the new data area address. æKY Devices.h æKL CloseDriver Control GetDCtlEntry KillIO opendriver OpenDriver PBControl PBControlAsync PBControlSync PBKillIO PBKillIOAsync PBKillIOSync PBStatus PBStatusAsync PBStatusSync SetChooserAlert Status activateMsg activDev AuxDCE AuxDCEHandle AuxDCEPtr buttonMsg cancelMsg cdevGenErr cdevMemErr cdevResErr cdevUnset chooserID clearDev closeDev copyDev cursorDev cutDev DCtlEntry DCtlHandle DCtlPtr deactivateMsg deactivDev deselectMsg fillListMsg getSelMsg hitDev hitMsg initDev initMsg keyEvtDev keyEvtMsg macDev newSelMsg normalMsg nulDev nulMsg okMsg pasteDev selectMsg startupMsg superMsg terminateMsg undoDev updateDev updateMsg æKY newSelMsg æFc Devices.h æT æD newSelMsg = 12, æC æKY fillListMsg æFc Devices.h æT æD fillListMsg = 13, æC æKY getSelMsg æFc Devices.h æT æD getSelMsg = 14, æC æKY selectMsg æFc Devices.h æT æD selectMsg = 15, æC æKY deselectMsg æFc Devices.h æT æD deselectMsg = 16, æC æKY terminateMsg æFc Devices.h æT æD terminateMsg = 17, æC æKY buttonMsg æFc Devices.h æT æD buttonMsg = 19, æC æKY chooserID æFc Devices.h æT æD chooserID = 1, æC æKY initDev æFc Devices.h æT æD initDev = 0, /*Time for cdev to initialize itself*/ æC »The initDev Message InitDev is an initialization message sent to allow the cdev to allocate its private storage (if any) and do any initial settings to buttons or controls. This message is sent when the user clicks on the cdev’s icon. Note that the dialog, cdev list, and all of the items in the cdev’s 'DITL' except user items will already have been drawn when the initDev message is sent. If your cdev doesn’t need any storage it should return the value that was passed to it in cdevValue. æKY hitDev æFc Devices.h æT æD hitDev = 1, /*Hit on one of my items*/ æC »The hitDev Message A hitDev message is sent when the user has clicked an enabled dialog item that belongs to the cdev. The dialog item number of the item hit is passed in the Item parameter. Remember that the Control Panel’s items precede yours, so you’ll want (Item – numItems) to determine which of your items was hit. If the Control Panel itself has n items, the first of the cdev’s items will be n+1 in the combined dialog item list. A cdev should not depend on any hardcoded value for numItems, since the number of items in Control Panel’s 'DITL' is likely to change in the future. Factoring in numItems need not mean an increase in your code size, or passing and adding numItems everywhere, or foregoing the constants that most developers use to identify specific items. You can do it easily, and neatly, as follows: 1. Subtract numItems from Item right away, and refer to your dialog items with constants as usual throughout the cdev. 2. Write simple envelope routines to enclose Dialog Manager procedures that require item number arguments. Add numItems only locally, within those routines and for the Dialog Manager calls only. This is demonstrated in the sample cdev. æKY closeDev æFc Devices.h æT æD closeDev = 2, /*Close yourself*/ æC æKY nulDev æFc Devices.h æT æD nulDev = 3, /*Null event*/ æC »The nulDev Message A nulDev message is sent to the cdev on every Control Panel run event. This allows the cdev to perform tasks that need to be executed continuously (insertion point blinking, for example). A cdev cannot assume any particular timing of calls from applications. Don’t use nulDev to refresh settings; see activDev, above. æKY updateDev æFc Devices.h æT æD updateDev = 4, /*Update event*/ æC æKY activDev æFc Devices.h æT æD activDev = 5, /*Activate event*/ æC #define activDev 5 /*Activate event*/ »The activDev Message An activDev message is sent to the cdev on every activate event. It allows the cdev to reset any items that may have changed while the Control Panel was inactive. It also allows the cdev to send things such as “lists activate” messages. æKY deactivDev æFc Devices.h æT æD deactivDev = 6, /*Deactivate event*/ æC æKY keyEvtDev æFc Devices.h æT æD keyEvtDev = 7, /*Key down/auto key*/ æC »The keyEvtDev Message A keyEvtDev message is sent to the cdev on every keyDown event and autoKey event. It allows the cdev to process key events. On return to the Control Panel, the key event will be processed by a call to dialogSelect in the Dialog Manager. A cdev that does not want the Toolbox Event Manager to do any further processing should change the what field of the EventRecord to nullEvent before returning to the Control Panel. æKY macDev æFc Devices.h æT æD macDev = 8, /*Decide whether or not to show up*/ æC »The macDev Message If the 'mach' resource has a 0 in Softmask and a –1 ($FFFF) in Hardmask, the first message a cdev will get is a macDev message. This is an opportunity for the cdev to determine whether it can run, and whether it should appear in the Control Panel’s cdev list. The cdev can do its own check to see which machine it is being run on, what hardware is connected, and what is in the slots (if it has slots). The cdev must then return a function result of 1 or 0. If a 0 is returned, the Control Panel will not display the cdev in the icon list. (Note that the Control Panel does not interpret this 0 or 1 as an error message as described under “Cdev Error Checking”.) The macDev call happens only once, and only when Softmask and Hardmask are 0 and FFFF. It is always the first call made to the cdev. #define macDev 8 /*Decide whether or not to show up*/ æKY undoDev æFc Devices.h æT æD undoDev = 9, æC æKY cutDev æFc Devices.h æT æD cutDev = 10, æC æKY copyDev æFc Devices.h æT æD copyDev = 11, æC æKY pasteDev æFc Devices.h æT æD pasteDev = 12, æC æKY clearDev æFc Devices.h æT æD clearDev = 13, æC æKY cursorDev æFc Devices.h æT æD cursorDev = 14, æC æKY cdevGenErr æFc Devices.h æT æD cdevGenErr = -1, /*General error; gray cdev w/o alert*/ æC æKY cdevMemErr æFc Devices.h æT æD cdevMemErr = 0, /*Memory shortfall; alert user please*/ æC æKY cdevResErr æFc Devices.h æT æD cdevResErr = 1, /*Couldn't get a needed resource; alert*/ æC æKY cdevUnset æFc Devices.h æT æD cdevUnset = 3, /* cdevValue is initialized to this*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY initMsg æFc Devices.h æT æD initMsg = 1, /*initialization*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY okMsg æFc Devices.h æT æD okMsg = 2, /*user clicked OK button*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY cancelMsg æFc Devices.h æT æD cancelMsg = 3, /*user clicked Cancel button*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY hitMsg æFc Devices.h æT æD hitMsg = 4, /*user clicked control in Options dialog*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY nulMsg æFc Devices.h æT æD nulMsg = 5, /*periodic event*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY updateMsg æFc Devices.h æT æD updateMsg = 6, /*update event*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY activateMsg æFc Devices.h æT æD activateMsg = 7, /*not used*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY deactivateMsg æFc Devices.h æT æD deactivateMsg = 8, /*not used*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY keyEvtMsg æFc Devices.h æT æD keyEvtMsg = 9, /*keyboard event*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY superMsg æFc Devices.h æT æD superMsg = 10, /*show superuser controls*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY normalMsg æFc Devices.h æT æD normalMsg = 11, /*show only normal controls*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY startupMsg æFc Devices.h æT æD startupMsg = 12, /*code has been loaded*/ æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: #define cdevUnset 3 /*initial value passed in cdevValue*/ #define cdevGenErr -1 /*generic cdev error*/ #define cdevMemErr 0 /*insufficient memory for cdev execution*/ #define cdevResErr 1 /*missing resource needed by cdev*/ After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY DCtlEntry DCtlPtr DCtlHandle æFc Devices.h æT struct æD struct DCtlEntry { Ptr dCtlDriver; short dCtlFlags; QHdr dCtlQHdr; long dCtlPosition; Handle dCtlStorage; short dCtlRefNum; long dCtlCurTicks; WindowPtr dCtlWindow; short dCtlDelay; short dCtlEMask; short dCtlMenu; }; typedef struct DCtlEntry DCtlEntry; typedef DCtlEntry *DCtlPtr, **DCtlHandle; æC »Device Control Entry The first time a driver is opened, information about it is read into a structure in memory called a device control entry. A device control entry contains the header of the driver’s I/O queue, the location of the driver’s routines, and other information. A device control entry is a 40-byte relocatable block located in the system heap. It’s locked while the driver is open, and unlocked while the driver is closed. Most of the data in the device control entry is stored and accessed only by the Device Manager, but in some cases the driver itself must store into it. The structure of a device control entry is shown below; note that the first four words of the driver are copied into the dCtlFlags, dCtlDelay, dCtlEMask, and dCtlMenu fields. TYPE DCtlEntry = RECORD dCtlDriver: Ptr; {pointer to ROM driver or } { handle to RAM driver} dCtlFlags: INTEGER; {flags} dCtlQHdr: QHdr; {driver I/O queue header} dCtlPosition: LONGINT; {byte position used by Read } { and Write calls} dCtlStorage: Handle; {handle to RAM driver's } { private storage} dCtlRefNum: INTEGER; {driver reference number} dCtlCurTicks: LONGINT; {used internally} dCtlWindow: WindowPtr; {pointer to driver's window} dCtlDelay: INTEGER; {number of ticks between } { periodic actions} dCtlEMask: INTEGER; {desk accessory event mask} dCtlMenu: INTEGER {menu ID of menu associated { with driver} END; DCtlPtr = ^DCtlEntry; DCtlHandle = ^DCtlPtr; The low-order byte of the dCtlFlags word contains the following flags: Bit number Meaning 5 Set if driver is open 6 Set if driver is RAM-based 7 Set if driver is currently executing Assembly-language note: These flags can be accessed with the global constants dOpened, dRAMBased, and drvrActive. The high-order byte of the dCtlFlags word contains flags copied from the drvrFlags word of the driver, as described above. DCtlQHdr contains the header of the driver’s I/O queue (described below). DCtlPosition is used only by drivers of block devices, and indicates the current source or destination position of a Read or Write call. The position is given as a number of bytes beyond the physical beginning of the medium used by the device. For example, if one logical block of data has just been read from a 3 1/2-inch disk via the Disk Driver, dCtlPosition will be 512. ROM drivers generally use locations in low memory for their local storage. RAM drivers may reserve memory within their code space, or allocate a relocatable block and keep a handle to it in dCtlStorage (if the block resides in the application heap, its handle will be set to NIL when the heap is reinitialized). You can get a handle to a driver’s device control entry by calling the Device Manager function GetDCtlEntry. æKY AuxDCE AuxDCEPtr AuxDCEHandle æFc Devices.h æT struct æD struct AuxDCE { Ptr dCtlDriver; short dCtlFlags; QHdr dCtlQHdr; long dCtlPosition; Handle dCtlStorage; short dCtlRefNum; long dCtlCurTicks; GrafPtr dCtlWindow; short dCtlDelay; short dCtlEMask; short dCtlMenu; char dCtlSlot; char dCtlSlotId; long dCtlDevBase; Ptr dCtlOwner; char dCtlExtDev; char fillByte; }; typedef struct AuxDCE AuxDCE; typedef AuxDCE *AuxDCEPtr, **AuxDCEHandle; æC æKY GetDCtlEntry æFc Devices.h æT Function æD pascal DCtlHandle GetDCtlEntry(short refNum); æDT DCtlHandle myVariable = GetDCtlEntry((short) refNum); æMM æRT 71 æRI II-190 æC æKY SetChooserAlert æFc Devices.h æT Function æD pascal Boolean SetChooserAlert(Boolean f); æDT Boolean myVariable = SetChooserAlert((Boolean) f); æRI V-431 æC If f is true, the Chooser will put up the page setup alert; if f is false it won’t. SetChooserAlert returns the original alert state. The application should restore the original alert state when it exits. _____________________________________________________________________________________ Assembly-language note: If the psAlert bit of the low-memory global HiliteMode is 0 then no page setup alert will be generated. Applications that set or clear this bit must be sure not to affect any other bits in the byte and to restore the bit as they leave. HiliteMode equ $938 psAlert equ 6 bclr #psAlert,HiliteMode bset #psAlert,HiliteMode _____________________________________________________________________________________ æKY OpenDriver æFc Devices.h æT Function æD pascal OSErr OpenDriver(ConstStr255Param name,short *drvrRefNum); æDT OSErr myVariable = OpenDriver((ConstStr255Param) name,(short *) drvrRefNum); æMM æRI II-178, N14-2 æC [Not in ROM] OpenDriver opens the device driver specified by name and returns its reference number in refNum. Result codes noErr No error badUnitErr Bad reference number dInstErr Couldn’t find driver in resource file openErr Driver can’t perform the requested reading or writing unitEmptyErr Bad reference number æKY opendriver æFc Devices.h æT Function æD OSErr opendriver(char *driverName,short *refNum); æDT OSErr myVariable = opendriver((char *) driverName,(short *) refNum); æC æKY CloseDriver æFc Devices.h æT Function æD pascal OSErr CloseDriver(short refNum); æDT OSErr myVariable = CloseDriver((short) refNum); æRI II-178 æC [Not in ROM] CloseDriver closes the device driver having the reference number refNum. Any pending I/O is completed, and the memory used by the driver is released. Warning: Before using this command to close a particular driver, refer to the chapter describing the driver for the consequences of closing it. Result codes noErr No error badUnitErr Bad reference number dRemoveErr Attempt to remove an open driver unitEmptyErr Bad reference number æKY Control æFc Devices.h æT Function æD pascal OSErr Control(short refNum,short csCode,const void *csParamPtr); æDT OSErr myVariable = Control((short) refNum,(short) csCode,(const void *) csParamPtr); æMM æRI II-186 æC [Not in ROM] Control sends control information to the device driver having the reference number refNum. The type of information sent is specified by csCode, and the information itself is pointed to by csParamPtr. The values passed in csCode and pointed to by csParamPtr depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY Status æFc Devices.h æT Function æD pascal OSErr Status(short refNum,short csCode,void *csParamPtr); æDT OSErr myVariable = Status((short) refNum,(short) csCode,(void *) csParamPtr); æMM æRI II-186 æC [Not in ROM] Status returns status information about the device driver having the reference number refNum. The type of information returned is specified by csCode, and the information itself is pointed to by csParamPtr. The values passed in csCode and pointed to by csParamPtr depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY KillIO æFc Devices.h æT Function æD pascal OSErr KillIO(short refNum); æDT OSErr myVariable = KillIO((short) refNum); æRI II-179 æC [Not in ROM] KillIO terminates all current and pending I/O with the device driver having the reference number refNum. Result codes noErr No error badUnitErr Bad reference number æKY PBControl æFc Devices.h æT Function æD pascal OSErr PBControl(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBControl((ParmBlkPtr) paramBlock,(Boolean) async); æMM æRI II-186 æC Trap macro _Control Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word --> 28 csParam record PBControl sends control information to the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information sent is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY PBControlSync æFc Devices.h æT Function æTN A004 æD #pragma parameter __D0 PBControlSync(__A0) pascal OSErr PBControlSync(ParmBlkPtr paramBlock) = 0xA004; æDT #pragma parameter __D0 myVariable = PBControlSync()(__A0); æMM æRI II-186 æC Trap macro _Control Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word --> 28 csParam record PBControl sends control information to the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information sent is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY PBControlAsync æFc Devices.h æT Function æTN A404 æD #pragma parameter __D0 PBControlAsync(__A0) pascal OSErr PBControlAsync(ParmBlkPtr paramBlock) = 0xA404; æDT #pragma parameter __D0 myVariable = PBControlAsync()(__A0); æMM æRI II-186 æC Trap macro _Control Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word --> 28 csParam record PBControl sends control information to the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information sent is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY PBStatus æFc Devices.h æT Function æD pascal OSErr PBStatus(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBStatus((ParmBlkPtr) paramBlock,(Boolean) async); æMM æRI II-186 æC Trap macro _Status Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word <-- 28 csParam record PBStatus returns status information about the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information returned is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY PBStatusSync æFc Devices.h æT Function æTN A005 æD #pragma parameter __D0 PBStatusSync(__A0) pascal OSErr PBStatusSync(ParmBlkPtr paramBlock) = 0xA005; æDT #pragma parameter __D0 myVariable = PBStatusSync()(__A0); æMM æRI II-186 æC Trap macro _Status Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word <-- 28 csParam record PBStatus returns status information about the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information returned is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY PBStatusAsync æFc Devices.h æT Function æTN A405 æD #pragma parameter __D0 PBStatusAsync(__A0) pascal OSErr PBStatusAsync(ParmBlkPtr paramBlock) = 0xA405; æDT #pragma parameter __D0 myVariable = PBStatusAsync()(__A0); æMM æRI II-186 æC Trap macro _Status Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word <-- 28 csParam record PBStatus returns status information about the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information returned is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY PBKillIO æFc Devices.h æT Function æD pascal OSErr PBKillIO(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBKillIO((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-187 æC Trap macro _KillIO Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBKillIO stops any current I/O request being processed, and removes all pending I/O requests from the I/O queue of the device driver having the reference number ioRefNum. The completion routine of each pending I/O request is called, with the ioResult field of each request equal to the result code abortErr. Result codes noErr No error badUnitErr Bad reference number unitEmptyErr Bad reference number æKY PBKillIOSync æFc Devices.h æT Function æTN A006 æD #pragma parameter __D0 PBKillIOSync(__A0) pascal OSErr PBKillIOSync(ParmBlkPtr paramBlock) = 0xA006; æDT #pragma parameter __D0 myVariable = PBKillIOSync()(__A0); æRI II-187 æC Trap macro _KillIO Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBKillIO stops any current I/O request being processed, and removes all pending I/O requests from the I/O queue of the device driver having the reference number ioRefNum. The completion routine of each pending I/O request is called, with the ioResult field of each request equal to the result code abortErr. Result codes noErr No error badUnitErr Bad reference number unitEmptyErr Bad reference number æKY PBKillIOAsync æFc Devices.h æT Function æTN A406 æD #pragma parameter __D0 PBKillIOAsync(__A0) pascal OSErr PBKillIOAsync(ParmBlkPtr paramBlock) = 0xA406; æDT #pragma parameter __D0 myVariable = PBKillIOAsync()(__A0); æRI II-187 æC Trap macro _KillIO Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBKillIO stops any current I/O request being processed, and removes all pending I/O requests from the I/O queue of the device driver having the reference number ioRefNum. The completion routine of each pending I/O request is called, with the ioResult field of each request equal to the result code abortErr. Result codes noErr No error badUnitErr Bad reference number unitEmptyErr Bad reference number æKY Dialogs.h æKL Alert CautionAlert CloseDialog CouldAlert CouldDialog DialogSelect DisposDialog DisposeDialog DlgCopy DlgCut DlgDelete DlgPaste DrawDialog ErrorSound findditem FindDItem FreeAlert FreeDialog GetAlrtStage GetDItem getitext GetIText GetNewDialog HideDItem InitDialogs IsDialogEvent ModalDialog newcdialog NewCDialog newdialog NewDialog NoteAlert paramtext ParamText ResetAlrtStage SelIText SetDAFont SetDItem setitext SetIText ShowDItem StopAlert UpdateDialog UpdtDialog AlertTemplate AlertTHndl AlertTPtr btnCtrl cancel cautionIcon chkCtrl ctrlItem DialogPeek DialogPtr DialogRecord DialogTemplate DialogTHndl DialogTPtr editText iconItem itemDisable ModalFilterProcPtr noteIcon ok picItem radCtrl resCtrl ResumeProcPtr SoundProcPtr StageList statText stopIcon userItem æKY ctrlItem æFc Dialogs.h æT æD ctrlItem = 4, æC æKY btnCtrl æFc Dialogs.h æT æD btnCtrl = 0, æC æKY chkCtrl æFc Dialogs.h æT æD chkCtrl = 1, æC æKY radCtrl æFc Dialogs.h æT æD radCtrl = 2, æC æKY resCtrl æFc Dialogs.h æT æD resCtrl = 3, æC æKY statText æFc Dialogs.h æT æD statText = 8, æC æKY editText æFc Dialogs.h æT æD editText = 16, æC æKY iconItem æFc Dialogs.h æT æD iconItem = 32, æC æKY picItem æFc Dialogs.h æT æD picItem = 64, æC æKY userItem æFc Dialogs.h æT æD userItem = 0, æC æKY itemDisable æFc Dialogs.h æT æD itemDisable = 128, æC æKY ok æFc Dialogs.h æT æD ok = 1, æC æKY cancel æFc Dialogs.h æT æD cancel = 2, æC æKY stopIcon æFc Dialogs.h æT æD stopIcon = 0, æC æKY noteIcon æFc Dialogs.h æT æD noteIcon = 1, æC æKY cautionIcon æFc Dialogs.h æT æD cautionIcon = 2, æC æKY StageList æFc Dialogs.h æT typedef æD typedef short StageList; æC »Alert Templates in Memory The data structure of an alert template is as follows: TYPE AlertTemplate = RECORD boundsRect: Rect; {becomes window's portRect} itemsID: INTEGER; {resource ID of item list} stages: StageList {alert stage information} END; BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The itemsID field contains the resource ID of the item list for the alert. The information in the stages field determines exactly what should happen at each stage of the alert. It's packed into a word that has the following structure: TYPE StageList = PACKED RECORD boldItm4: 0..1; {default button item number minus 1} boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} sound4: 0..3 {sound number} boldItm3: 0..1; boxDrwn3: BOOLEAN; sound3: 0..3 boldItm2: 0..1; boxDrwn2: BOOLEAN; sound2: 0..3 boldItm1: 0..1; boxDrwn1: BOOLEAN; sound1: 0..3 END; Notice that the information is stored in reverse order—for the fourth stage first, and for the first stage last. The boldItm field indicates which button should be the default button (and therefore boldly outlined in the alert box). If the first two items in the alert’s item list are the OK button and the Cancel button, respectively, 0 will refer to the OK button and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1 is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel buttons, respectively. Whatever the item having the corresponding item number happens to be, a bold rounded-corner rectangle will be drawn outside its display rectangle. Note: When deciding where to place items in an alert box, be sure to allow room for any bold outlines that may be drawn. The boxDrwn field is TRUE if the alert box is to be drawn. The sound field specifies which sound should be emitted at this stage of the alert, with a number from 0 to 3 that’s passed to the current sound procedure. You can call ErrorSound to specify your own sound procedure; if you don’t, the standard sound procedure will be used (as described earlier in the “Alerts” section). You access the alert template by converting the handle returned by the Resource Manager to a template handle: TYPE AlertTHndl = ^AlertTPtr; AlertTPtr = ^AlertTemplate; Assembly-language note: Rather than offsets into the fields of the StageList data structure, there are masks for accessing the information stored for an alert stage in a stages word; they’re listed in the summary at the end of this chapter. æKY DialogPtr æFc Dialogs.h æT typedef æD typedef WindowPtr DialogPtr; æC »Dialog Pointers There are two types of dialog pointer, DialogPtr and DialogPeek, analogous to the window pointer types WindowPtr and WindowPeek. Most programmers will only need to use DialogPtr. The Dialog Manager defines the following type of dialog pointer: TYPE DialogPtr = WindowPtr; It can do this because the first field of a dialog record contains the window record for the dialog window. This type of pointer can be used to access fields of the window record or can be passed to Window Manager routines that expect window pointers as parameters. Since the WindowPtr data type is itself defined as GrafPtr, this type of dialog pointer can also be used to access fields of the dialog window’s grafPort or passed to QuickDraw routines that expect pointers to grafPorts as parameters. For programmers who want to access dialog record fields beyond the window record, the Dialog Manager also defines the following type of dialog pointer: TYPE DialogPeek = ^DialogRecord; Assembly-language note: From assembly language, of course, there’s no type checking on pointers, and the two types of pointer are equal. _______________________________________________________________________________ »The DialogRecord Data Type For those who want to know more about the data structure of a dialog record, the exact structure is given here. TYPE DialogRecord = RECORD window: WindowRecord; {dialog window} items: Handle; {item list} textH: TEHandle; {current editText item} editField: INTEGER; {editText item number minus 1} editOpen: INTEGER; {used internally} aDefItem: INTEGER {default button item number} END; The window field contains the window record for the dialog window. The items field contains a handle to the item list used for the dialog. (Remember that after reading an item list from a resource file, the Dialog Manager makes a copy of it and uses that copy.) Note: To get or change information about an item in a dialog, you pass the dialog pointer and the item number to a Dialog Manager procedure. You’ll never access information directly through the handle to the item list. The Dialog Manager uses the next three fields when there are one or more editText items in the dialog. If there’s more than one such item, these fields apply to the one that currently is selected or displays the insertion point. The textH field contains the handle to the edit record used by TextEdit. EditField is 1 less than the item number of the current editText item, or –1 if there’s no editText item in the dialog. The editOpen field is used internally by the Dialog Manager. Note: Actually, a single edit record is shared by all editText items; any changes you make to it will apply to all such items. See the TextEdit chapter for details about what kinds of changes you can make. The aDefItem field is used for modal dialogs and alerts, which are treated internally as special modal dialogs. It contains the item number of the default button. The default button for a modal dialog is the first item in the item list, so this field contains 1 for modal dialogs. The default button for an alert is specified in the alert template; see the following section for more information. _______________________________________________________________________________ »THE DRAWING ENVIRONMENT: GRAFPORT _______________________________________________________________________________ A grafPort is a complete drawing environment that defines where and how graphic operations will take place. You can have many grafPorts open at once, and each one will have its own coordinate system, drawing pattern, background pattern, pen size and location, character font and style, and bit map in which drawing takes place. You can instantly switch from one port to another. GrafPorts are the structures upon which a program builds windows, which are fundamental to the Macintosh “overlapping windows” user interface. Besides being used for windows on the screen, grafPorts are used for printing and for off-screen drawing. A grafPort is defined as follows: TYPE GrafPtr = ^GrafPort; GrafPort = RECORD device: INTEGER; {device-specific information} portBits: BitMap; {grafPort's bit map} portRect: Rect; {grafPort's rectangle} visRgn: RgnHandle; {visible region} clipRgn: RgnHandle; {clipping region} bkPat: Pattern; {background pattern} fillPat: Pattern; {fill pattern} pnLoc: Point; {pen location} pnSize: Point; {pen size} pnMode: INTEGER; {pen's transfer mode} pnPat: Pattern; {pen pattern} pnVis: INTEGER; {pen visibility} txFont: INTEGER; {font number for text} txFace: Style; {text's character style} txMode: INTEGER; {text's transfer mode} txSize: INTEGER; {font size for text} spExtra: Fixed; {extra space} fgColor: LONGINT; {foreground color} bkColor: LONGINT; {background color} colrBit: INTEGER; {color bit} patStretch: INTEGER; {used internally} picSave: Handle; {picture being saved} rgnSave: Handle; {region being saved} polySave: Handle; {polygon being saved} grafProcs: QDProcsPtr {low-level drawing routines} END; Note that picSave is a Handle used internally by QuickDraw while it is saving a picture, and rgnSave and polySave are used by QuickDraw as flags; they are set to “1” when the corresponding action is taking place. All QuickDraw operations refer to grafPorts via grafPtrs. (For historical reasons, grafPort is one of the few objects in the Macintosh system software that’s referred to by a pointer rather than a handle.) Warning: You can access all fields and subfields of a grafPort normally, but you should not store new values directly into them. QuickDraw has routines for altering all fields of a grafPort, and using these routines ensures that changing a grafPort produces no unusual side effects. The device field of a grafPort contains device-specific information that’s used by the Font Manager to achieve the best possible results when drawing text in the grafPort. There may be physical differences in the same logical font for different output devices, to ensure the highest-quality printing on the device being used. The default value of the device field is 0, for best results on output to the screen. For more information, see the Font Manager chapter. The portBits field is the bit map that points to the bit image to be used by the grafPort. The default bit map uses the entire screen as its bit image. The bit map may be changed to indicate a different structure in memory: All graphics routines work in exactly the same way regardless of whether their effects are visible on the screen. A program can, for example, prepare an image to be printed on a printer without ever displaying the image on the screen, or develop a picture in an off-screen bit map before transferring it to the screen. The portBits.bounds rectangle determines the coordinate system of the grafPort; all other coordinates in the grafPort are expressed in this system. The portRect field is a rectangle that defines a subset of the bit map that will be used for drawing: All drawing done by the application occurs inside the portRect. Its coordinates are in the coordinate system defined by the portBits.bounds rectangle. The portRect usually falls within the portBits.bounds rectangle, but it’s not required to do so. The portRect usually defines the “writable” interior area of a window, document, or other object on the screen. The visRgn field is manipulated by the Window Manager; you will normally never change a grafPort’s visRgn. It indicates the region of the grafPort that’s actually visible on the screen, that is, the part of the window that’s not covered by other windows. For example, if you move one window in front of another, the Window Manager logically removes the area of overlap from the visRgn of the window in back. When you draw into the back window, whatever’s being drawn is clipped to the visRgn so that it doesn’t run over onto the front window. The default visRgn is set to the portRect. The clipRgn is the grafPort’s clipping region, an arbitrary region that you can use to limit drawing to any region within the portRect. If, for example, you want to draw a half circle on the screen, you can set the clipRgn to half the square that would enclose the whole circle, and then draw the whole circle. Only the half within the clipRgn will actually be drawn in the grafPort. The default clipRgn is set arbitrarily large, you have full control over its setting; as a matter of recommended programming practice, it is advisable to make the default clipRgn rectangle smaller. Figure 10 illustrates a typical bit map (as defined by portBits), portRect, visRgn, and clipRgn. •••Refer to Figure 10.••• Figure 10–GrafPort Regions The bkPat and fillPat fields of a grafPort contain patterns used by certain QuickDraw routines. BkPat is the “background” pattern that’s used when an area is erased or when bits are scrolled out of it. When asked to fill an area with a specified pattern, QuickDraw stores the given pattern in the fillPat field and then calls a low-level drawing routine that gets the pattern from that field. The various graphic operations are discussed in detail later in the descriptions of individual QuickDraw routines. Of the next ten fields, the first five determine characteristics of the graphics pen and the last five determine characteristics of any text that may be drawn; these are described in separate sections below. The fgColor, bkColor, and colrBit fields contain values related to drawing in color. FgColor is the grafPort’s foreground color and bkColor is its background color. ColrBit tells the color imaging software which plane of the color picture to draw into. For more information, see “Drawing in Color” in the section “General Discussion of Drawing”. The patStretch field is used during output to a printer to expand patterns if necessary. The application should not change its value. The picSave, rgnSave, and polySave fields reflect the state of picture, region, and polygon definition, respectively. The application shouldn’t be concerned about exactly what information the handle, if any, leads to; you may, however, save the current value of rgnSave, set the field to NIL to disable the region definition, and later restore it to the saved value to resume the region definition. The picSave and polySave fields work similarly for pictures and polygons. Finally, the grafProcs field may point to a special data structure that the application stores into if it wants to customize QuickDraw drawing routines or use QuickDraw in other advanced, highly specialized ways (see “Customizing QuickDraw Operations”). If grafProcs is NIL, QuickDraw responds in the standard ways described in this chapter. _______________________________________________________________________________ »Pen Characteristics The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal with the graphics “pen”. Each grafPort has one and only one such pen, which is used for drawing lines, shapes, and text. The pen has four characteristics: a location, a size (height and width), a drawing mode, and a drawing pattern (see Figure 11). •••Refer to Figure 11.••• Figure 11–A Graphics Pen The pnLoc field specifies the point where QuickDraw will begin drawing the next line, shape, or character. It can be anywhere on the coordinate plane: There are no restrictions on the movement or placement of the pen. Remember that the pen location is a point in the grafPort’s coordinate system, not a pixel in a bit image. The top left corner of the pen is at the pen location; the pen hangs below and to the right of this point. The pen is rectangular in shape, and its width and height are specified by pnSize. The default size is a 1-by-1-bit square; the width and height can range from (0,0) to (30000,30000). If either the pen width or the pen height is less than 1, the pen will not draw. The pnMode and pnPat fields of a grafPort determine how the bits under the pen are affected when lines or shapes are drawn. The pnPat is a pattern that’s used like the “ink” in the pen. This pattern, like all other patterns drawn in the grafPort, is always aligned with the port’s coordinate system: The top left corner of the pattern is aligned with the top left corner of the portRect, so that adjacent areas of the same pattern will blend into a continuous, coordinated pattern. The pnMode field determines how the pen pattern is to affect what’s already in the bit image when lines or shapes are drawn. When the pen draws, QuickDraw first determines what bits in the bit image will be affected and finds their corresponding bits in the pattern. It then does a bit-by-bit comparison based on the pen mode, which specifies one of eight Boolean operations to perform. The resulting bit is stored into its proper place in the bit image. The pen modes are described under “Transfer Modes” in the section “General Discussion of Drawing”. The pnVis field determines the pen’s visibility, that is, whether it draws on the screen. For more information, see the descriptions of HidePen and ShowPen under “Pen and Line-Drawing Routines” in the “QuickDraw Routines” section. _______________________________________________________________________________ »Text Characteristics The txFont, txFace, txMode, txSize, and spExtra fields of a grafPort determine how text will be drawn—the font, style, and size of characters and how they will be placed in the bit image. QuickDraw can draw characters as quickly and easily as it draws lines and shapes, and in many prepared fonts. Font means the complete set of characters of one typeface. The characters may be drawn in any size and character style (that is, with stylistic variations such as bold, italic, and underline). Figure 12 shows two characters drawn by QuickDraw and some terms associated with drawing text. •••Refer to Figure 12.••• Figure 12–QuickDraw Characters Text is drawn with the base line positioned at the pen location. The txFont field is a font number that identifies the character font to be used in the grafPort. The font number 0 represents the system font. For more information about the system font, the other font numbers recognized by the Font Manager, and the construction, layout, and loading of fonts, see the Font Manager chapter. A character font is defined as a collection of images that make up the individual characters of the font. The characters can be of unequal widths, and they’re not restricted to their “cells”: The lower curl of a lowercase j, for example, can stretch back under the previous character (typographers call this kerning). A font can consist of up to 255 distinct characters, yet not all characters need to be defined in a single font. In addition, each font contains a missing symbol to be drawn in case of a request to draw a character that’s missing from the font. The txFace field controls the character style of the text with values from the set defined by the Style data type: TYPE StyleItem = (bold,italic,underline,outline,shadow,condense,extend); Style = SET OF StyleItem; Assembly-language note: In assembly language, this set is stored as a word whose low-order byte contains bits representing the style. The bit numbers are specified by the following global constants: boldBit .EQU 0 italicBit .EQU 1 ulineBit .EQU 2 outlineBit .EQU 3 shadowBit .EQU 5 extendBit .EQU 6 If all bits are 0, it represents the plain character style. You can apply stylistic variations either alone or in combination; Figure 13 illustrates some as applied to the Geneva font. Most combinations usually look good only for large font sizes. •••Refer to Figure 13.••• Figure 13–Stylistic Variations If you specify bold, each character is repeatedly drawn one bit to the right an appropriate number of times for extra thickness. Italic adds an italic slant to the characters. Character bits above the base line are skewed right; bits below the base line are skewed left. Underline draws a line below the base line of the characters. If part of a character descends below the base line (as “y” in Figure 13), the underline isn’t drawn through the pixel on either side of the descending part. Outline makes a hollow, outlined character rather than a solid one. Shadow also makes an outlined character, but the outline is thickened below and to the right of the character to achieve the effect of a shadow. If you specify bold along with outline or shadow, the hollow part of the character is widened. Condense and extend affect the horizontal distance between all characters, including spaces. Condense decreases the distance between characters and extend increases it, by an amount that the Font Manager determines is appropriate. The txMode field controls the way characters are placed in the bit image. It functions much like a pnMode: When a character is drawn, QuickDraw determines which bits in the bit image will be affected, does a bit-by-bit comparison based on the mode, and stores the resulting bits into the bit image. These modes are described under “Transfer Modes” in the section “General Discussion of Drawing”. Only three of them—srcOr, srcXor, and srcBic—should be used for drawing text. Note: If you use scrCopy, some extra blank space will be appended at the end of the text. The txSize field specifies the font size in points (where “point” is a typographical term meaning approximately 1/72 inch). Any size from 1 to 127 points may be specified. If the Font Manager doesn’t have the font in a specified size, it will scale a size it does have as necessary to produce the size desired. A value of 0 in this field represents the system font size (12 points). Finally, the spExtra field is useful when a line of characters is to be drawn justified such that it’s aligned with both a left and a right margin (sometimes called “full justification”). SpExtra contains a fixed-point number equal to the average number of pixels by which each space character should be widened to fill out the line. The Fixed data type is described in the Macintosh Memory Management: An Introduction chapter. _______________________________________________________________________________ »COORDINATES IN GRAFPORTS _______________________________________________________________________________ Each grafPort has its own local coordinate system. All fields in the grafPort are expressed in these coordinates, and all calculations and actions performed in QuickDraw use the local coordinate system of the currently selected port. Two things are important to remember: • Each grafPort maps a portion of the coordinate plane into a similarly- sized portion of a bit image. • The portBits.bounds rectangle defines the local coordinates for a grafPort. The top left corner of portBits.bounds is always aligned around the first bit in the bit image; the coordinates of that corner “anchor” a point on the grid to that bit in the bit image. This forms a common reference point for multiple grafPorts that use the same bit image (such as the screen); given a portBits.bounds rectangle for each port, you know that their top left corners coincide. The relationship between the portBits.bounds and portRect rectangles is very important: The portBits.bounds rectangle establishes a coordinate system for the port, and the portRect rectangle indicates the section of the coordinate plane (and thus the bit image) that will be used for drawing. The portRect usually falls inside the portBits.bounds rectangle, but it’s not required to do so. When a new grafPort is created, its bit map is set to point to the entire screen, and both the portBits.bounds and the portRect are set to rectangles enclosing the screen. The point (0,0) corresponds to the screen’s top left corner. You can redefine the local coordinates of the top left corner of the grafPort’s portRect, using the SetOrigin procedure. This offsets the coordinates of the grafPort’s portBits.bounds rectangle, recalculating the coordinates of all points in the grafPort to be relative to the new corner coordinates. For example, consider these procedure calls: SetPort(gamePort); SetOrigin(90,80) The call to SetPort sets the current grafPort to gamePort; the call to SetOrigin changes the local coordinates of the top left corner of that port’s portRect to (90,80) (see Figure 14). •••Refer to Figure 14.••• Figure 14–Changing Local Coordinates This offsets the coordinates of the following elements: gamePort^.portBits.bounds gamePort^.portRect gamePort^.visRgn These three elements are always kept “in sync”. Notice that when the local coordinates of a grafPort are offset, the grafPort’s clipRgn and pen location are not offset. A good way to think of it is that the port’s structure “sticks” to the screen, while the document in the grafPort (along with the pen and clipRgn) “sticks” to the coordinate system. For example, in Figure 14, before SetOrigin, the visRgn and clipRgn are the same as the portRect. After the SetOrigin call, the locations of portBits.bounds, portRect, and visRgn do not change on the screen; their coordinates are simply offset. As always, the top left corner of portBits.bounds remains “anchored” around the first bit in the bit image (the first pixel on the screen); the image on the screen doesn’t move as a result of SetOrigin. However, the pen location and clipRgn do move on the screen; the top left corner of the clipRgn is still (100,100), but this location has moved down and to the right, and the pen has similarly moved. If you’re moving, comparing, or otherwise dealing with mathematical items in different grafPorts (for example, finding the intersection of two regions in two different grafPorts), you must adjust to a common coordinate system before you perform the operation. A QuickDraw procedure, LocalToGlobal, lets you convert a point’s local coordinates to a global coordinate system where the top left corner of the bit image is (0,0); by converting the various local coordinates to global coordinates, you can compare and mix them with confidence. For more information, see the description of LocaltoGlobal under “Calculations with Points” in the “QuickDraw Routines” section. æKY ResumeProcPtr æFc Dialogs.h æT typedef æD typedef pascal void (*ResumeProcPtr)(void); æC æKY SoundProcPtr æFc Dialogs.h æT typedef æD typedef pascal void (*SoundProcPtr)(void); æC æKY ModalFilterProcPtr æFc Dialogs.h æT typedef æD typedef pascal Boolean (*ModalFilterProcPtr)(DialogPtr theDialog, EventRecord *theEvent, short *itemHit); æC æKY DialogRecord DialogPeek æFc Dialogs.h æT struct æD struct DialogRecord { WindowRecord window; Handle items; TEHandle textH; short editField; short editOpen; short aDefItem; }; typedef struct DialogRecord DialogRecord; typedef DialogRecord *DialogPeek; æC »The DialogRecord Data Type For those who want to know more about the data structure of a dialog record, the exact structure is given here. TYPE DialogRecord = RECORD window: WindowRecord; {dialog window} items: Handle; {item list} textH: TEHandle; {current editText item} editField: INTEGER; {editText item number minus 1} editOpen: INTEGER; {used internally} aDefItem: INTEGER {default button item number} END; The window field contains the window record for the dialog window. The items field contains a handle to the item list used for the dialog. (Remember that after reading an item list from a resource file, the Dialog Manager makes a copy of it and uses that copy.) Note: To get or change information about an item in a dialog, you pass the dialog pointer and the item number to a Dialog Manager procedure. You’ll never access information directly through the handle to the item list. The Dialog Manager uses the next three fields when there are one or more editText items in the dialog. If there’s more than one such item, these fields apply to the one that currently is selected or displays the insertion point. The textH field contains the handle to the edit record used by TextEdit. EditField is 1 less than the item number of the current editText item, or –1 if there’s no editText item in the dialog. The editOpen field is used internally by the Dialog Manager. Note: Actually, a single edit record is shared by all editText items; any changes you make to it will apply to all such items. See the TextEdit chapter for details about what kinds of changes you can make. The aDefItem field is used for modal dialogs and alerts, which are treated internally as special modal dialogs. It contains the item number of the default button. The default button for a modal dialog is the first item in the item list, so this field contains 1 for modal dialogs. The default button for an alert is specified in the alert template; see the following section for more information. æKY DialogTemplate DialogTPtr DialogTHndl æFc Dialogs.h æT struct æD struct DialogTemplate { Rect boundsRect; short procID; Boolean visible; Boolean filler1; Boolean goAwayFlag; Boolean filler2; long refCon; short itemsID; Str255 title; }; typedef struct DialogTemplate DialogTemplate; typedef DialogTemplate *DialogTPtr, **DialogTHndl; æC »Dialog Templates in Memory The data structure of a dialog template is as follows: TYPE DialogTemplate = RECORD boundsRect: Rect; {becomes window's portRect} procID: INTEGER; {window definiton ID} visible: BOOLEAN; {TRUE if visible} filler1: BOOLEAN; {not used} goAwayFlag: BOOLEAN; {TRUE if has go-away region} filler2: BOOLEAN; {not used} refCon: LONGINT; {window's reference value} itemsID: INTEGER; {resource ID of item list} title: Str255 {window's title} END; The filler1 and filler2 fields are there because for historical reasons the goAwayFlag and refCon fields have to begin on a word boundary. The itemsID field contains the resource ID of the dialog’s item list. The other fields are the same as the parameters of the same name in the NewDialog function; they provide information about the dialog window. You access the dialog template by converting the handle returned by the Resource Manager to a template handle: TYPE DialogTHndl = ^DialogTPtr; DialogTPtr = ^DialogTemplate; æKY AlertTemplate AlertTPtr AlertTHndl æFc Dialogs.h æT struct æD struct AlertTemplate { Rect boundsRect; short itemsID; StageList stages; }; typedef struct AlertTemplate AlertTemplate; typedef AlertTemplate *AlertTPtr, **AlertTHndl; æC »Alert Templates in Memory The data structure of an alert template is as follows: TYPE AlertTemplate = RECORD boundsRect: Rect; {becomes window's portRect} itemsID: INTEGER; {resource ID of item list} stages: StageList {alert stage information} END; BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The itemsID field contains the resource ID of the item list for the alert. The information in the stages field determines exactly what should happen at each stage of the alert. It's packed into a word that has the following structure: TYPE StageList = PACKED RECORD boldItm4: 0..1; {default button item number minus 1} boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} sound4: 0..3 {sound number} boldItm3: 0..1; boxDrwn3: BOOLEAN; sound3: 0..3 boldItm2: 0..1; boxDrwn2: BOOLEAN; sound2: 0..3 boldItm1: 0..1; boxDrwn1: BOOLEAN; sound1: 0..3 END; Notice that the information is stored in reverse order—for the fourth stage first, and for the first stage last. The boldItm field indicates which button should be the default button (and therefore boldly outlined in the alert box). If the first two items in the alert’s item list are the OK button and the Cancel button, respectively, 0 will refer to the OK button and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1 is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel buttons, respectively. Whatever the item having the corresponding item number happens to be, a bold rounded-corner rectangle will be drawn outside its display rectangle. Note: When deciding where to place items in an alert box, be sure to allow room for any bold outlines that may be drawn. The boxDrwn field is TRUE if the alert box is to be drawn. The sound field specifies which sound should be emitted at this stage of the alert, with a number from 0 to 3 that’s passed to the current sound procedure. You can call ErrorSound to specify your own sound procedure; if you don’t, the standard sound procedure will be used (as described earlier in the “Alerts” section). You access the alert template by converting the handle returned by the Resource Manager to a template handle: TYPE AlertTHndl = ^AlertTPtr; AlertTPtr = ^AlertTemplate; Assembly-language note: Rather than offsets into the fields of the StageList data structure, there are masks for accessing the information stored for an alert stage in a stages word; they’re listed in the summary at the end of this chapter. æKY InitDialogs æFc Dialogs.h æT Function æTN A97B æD pascal void InitDialogs(ResumeProcPtr resumeProc) = 0xA97B; æDT InitDialogs((ResumeProcPtr) resumeProc); æRI I-411, P-107, 112, 174 æC Call InitDialogs once before all other Dialog Manager routines, to initialize the Dialog Manager. InitDialogs does the following initialization: • It saves the pointer passed in resumeProc, if any, for access by the System Error Handler in case a fatal system error occurs. ResumeProc can be a pointer to a resume procedure, as described in the System Error Handler chapter, or NIL if no such procedure is desired. Assembly-language note: InitDialogs stores the address of the resume procedure in a global variable named ResumeProc. • It installs the standard sound procedure. • It passes empty strings to ParamText. æKY ErrorSound æFc Dialogs.h æT Function æTN A98C æD pascal void ErrorSound(SoundProcPtr soundProc) = 0xA98C; æDT ErrorSound((SoundProcPtr) soundProc); æRI I-411 æC ErrorSound sets the sound procedure for alerts to the procedure pointed to by soundProc; if you don’t call ErrorSound, the Dialog Manager uses the standard sound procedure. (For details, see the “Alerts” section.) If you pass NIL for soundProc, there will be no sound (or menu bar blinking) at all. Assembly-language note: The address of the sound procedure being used is stored in the global variable DABeeper. æKY NewDialog æFc Dialogs.h æT Function æTN A97D æD pascal DialogPtr NewDialog(void *wStorage,const Rect *boundsRect,ConstStr255Param title, Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon, Handle itmLstHndl) = 0xA97D; æDT DialogPtr myVariable = NewDialog((void *) wStorage,(const Rect *) boundsRect,(ConstStr255Param) title,() Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,() Handle itmLstHndl); æMM æRI I-412, P-107, 177 æC NewDialog creates a dialog as specified by its parameters and returns a pointer to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog window; the meanings of these parameters are summarized below. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. Note: Advanced programmers can create their own item lists in memory rather than have them read from a resource file. The exact format is given later under “Formats of Resources for Dialogs and Alerts”. DStorage is analogous to the wStorage parameter of NewWindow; it’s a pointer to the storage to use for the dialog record. If you pass NIL for dStorage, the dialog record will be allocated in the heap (which, in the case of modeless dialogs, may cause the heap to become fragmented). BoundsRect, a rectangle given in global coordinates, determines the dialog window’s size and location. It becomes the portRect of the window’s grafPort. Remember that the top coordinate of this rectangle should be at least 25 points below the top of the screen for a modal dialog, to allow for the menu bar and the border around the portRect, and at least 40 points below the top of the screen for a modeless dialog, to allow for the menu bar and the window’s title bar. Title is the title of a modeless dialog box; pass the empty string for modal dialogs. If the visible parameter is TRUE, the dialog window is drawn on the screen. If it’s FALSE, the window is initially invisible and may later be shown with a call to the Window Manager procedure ShowWindow. Note: NewDialog generates an update event for the entire window contents, so the items aren’t drawn immediately, with the exception of controls. The Dialog Manager calls the Control Manager to draw controls, and the Control Manager draws them immediately rather than via the standard update mechanism. Because of this, the Dialog Manager calls the Window Manager procedure ValidRect for the enclosing rectangle of each control, so the controls won’t be drawn twice. If you find that the other items aren’t being drawn soon enough after the controls, try making the window invisible initially and then calling ShowWindow to show it. ProcID is the window definition ID, which leads to the window definition function for this type of window. The window definition IDs for the standard types of dialog window are dBoxProc for the modal type and documentProc for the modeless type. The behind parameter specifies the window behind which the dialog window is to be placed on the desktop. Pass POINTER(–1) to bring up the dialog window in front of all other windows. GoAwayFlag applies to modeless dialog boxes; if it’s TRUE, the dialog window has a close box in its title bar when the window is active. RefCon is the dialog window’s reference value, which the application may store into and access for any purpose. NewDialog sets the font of the dialog window’s grafPort to the system font or, if you previously called SetDAFont, to the specified font. It also sets the window class in the window record to dialogKind. æKY newdialog æFc Dialogs.h æT Function æTN A97D æD DialogPtr newdialog(void *wStorage,const Rect *boundsRect,char *title,Boolean visible, short procID,WindowPtr behind,Boolean goAwayFlag,long refCon,Handle itmLstHndl); æDT DialogPtr myVariable = newdialog((void *) wStorage,(const Rect *) boundsRect,(char *) title,(Boolean) visible,() short procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,(Handle) itmLstHndl); æMM æRI I-412, P-107, 177 æC NewDialog creates a dialog as specified by its parameters and returns a pointer to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog window; the meanings of these parameters are summarized below. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. Note: Advanced programmers can create their own item lists in memory rather than have them read from a resource file. The exact format is given later under “Formats of Resources for Dialogs and Alerts”. DStorage is analogous to the wStorage parameter of NewWindow; it’s a pointer to the storage to use for the dialog record. If you pass NIL for dStorage, the dialog record will be allocated in the heap (which, in the case of modeless dialogs, may cause the heap to become fragmented). BoundsRect, a rectangle given in global coordinates, determines the dialog window’s size and location. It becomes the portRect of the window’s grafPort. Remember that the top coordinate of this rectangle should be at least 25 points below the top of the screen for a modal dialog, to allow for the menu bar and the border around the portRect, and at least 40 points below the top of the screen for a modeless dialog, to allow for the menu bar and the window’s title bar. Title is the title of a modeless dialog box; pass the empty string for modal dialogs. If the visible parameter is TRUE, the dialog window is drawn on the screen. If it’s FALSE, the window is initially invisible and may later be shown with a call to the Window Manager procedure ShowWindow. Note: NewDialog generates an update event for the entire window contents, so the items aren’t drawn immediately, with the exception of controls. The Dialog Manager calls the Control Manager to draw controls, and the Control Manager draws them immediately rather than via the standard update mechanism. Because of this, the Dialog Manager calls the Window Manager procedure ValidRect for the enclosing rectangle of each control, so the controls won’t be drawn twice. If you find that the other items aren’t being drawn soon enough after the controls, try making the window invisible initially and then calling ShowWindow to show it. ProcID is the window definition ID, which leads to the window definition function for this type of window. The window definition IDs for the standard types of dialog window are dBoxProc for the modal type and documentProc for the modeless type. The behind parameter specifies the window behind which the dialog window is to be placed on the desktop. Pass POINTER(–1) to bring up the dialog window in front of all other windows. GoAwayFlag applies to modeless dialog boxes; if it’s TRUE, the dialog window has a close box in its title bar when the window is active. RefCon is the dialog window’s reference value, which the application may store into and access for any purpose. NewDialog sets the font of the dialog window’s grafPort to the system font or, if you previously called SetDAFont, to the specified font. It also sets the window class in the window record to dialogKind. æKY GetNewDialog æFc Dialogs.h æT Function æTN A97C æD pascal DialogPtr GetNewDialog(short dialogID,void *dStorage,WindowPtr behind) = 0xA97C; æDT DialogPtr myVariable = GetNewDialog((short) dialogID,(void *) dStorage,(WindowPtr) behind); æMM æRT 4,34 æRI I-413, V-284, N4-1, P-107, 172 æC Like NewDialog (above), GetNewDialog creates a dialog as specified by its parameters and returns a pointer to the new dialog. Instead of having the parameters boundsRect, title, visible, procID, goAwayFlag, and refCon, GetNewDialog has a single dialogID parameter, where dialogID is the resource ID of a dialog template that supplies the same information as those parameters. The dialog template also contains the resource ID of the dialog’s item list. After calling the Resource Manager to read the item list into memory (if it’s not already in memory), GetNewDialog makes a copy of the item list and uses that copy; thus you may have multiple independent dialogs whose items have the same types, locations, and initial contents. The dStorage and behind parameters of GetNewDialog have the same meaning as in NewDialog. Warning: If either the dialog template resource or the item list resource can’t be read, the function result is undefined. Note: GetNewDialog doesn’t release the memory occupied by the resources. The GetNewDialog routine will attempt to load a 'dctb' resource and returns a pointer to a color grafPort if the resource exists. If no 'dctb' resource is present, GetNewDialog returns a pointer to an old grafPort. The dialog color table is copied before it is passed to SetWinSize unless its ctSize field is equal to –1, indicating that the default window colors are to be used instead. The copy is made so that the color table resource can be purged without affecting the dialog. The color dialog item list resource is duplicated as well, so it can be purgeable. æKY CloseDialog æFc Dialogs.h æT Function æTN A982 æD pascal void CloseDialog(DialogPtr theDialog) = 0xA982; æDT CloseDialog((DialogPtr) theDialog); æMM æRI I-413, P-107, 167 æC CloseDialog removes theDialog’s window from the screen and deletes it from the window list, just as when the Window Manager procedure CloseWindow is called. It releases the memory occupied by the following: • The data structures associated with the dialog window (such as the window’s structure, content, and update regions). • All the items in the dialog (except for pictures and icons, which might be shared resources), and any data structures associated with them. For example, it would dispose of the region occupied by the thumb of a scroll bar, or a similar region for some other control in the dialog. CloseDialog does not dispose of the dialog record or the item list. Figure 10 illustrates the effect of CloseDialog (and DisposDialog, described below). •••Refer to Figure 10.••• Figure 10–CloseDialog and DisposDialog Call CloseDialog when you’re done with a dialog if you supplied NewDialog or GetNewDialog with a pointer to the dialog storage (in the dStorage parameter) when you created the dialog. Note: Even if you didn’t supply a pointer to the dialog storage, you may want to call CloseDialog if you created the dialog with NewDialog. You would call CloseDialog if you wanted to keep the item list around (since, unlike GetNewDialog, NewDialog does not use a copy of the item list). æKY DisposDialog æFc Dialogs.h æT Function æTN A983 æD pascal void DisposDialog(DialogPtr theDialog) = 0xA983; æDT DisposDialog((DialogPtr) theDialog); æRI I-415 æC DisposDialog calls CloseDialog (above) and then releases the memory occupied by the dialog’s item list and dialog record. Call DisposDialog when you’re done with a dialog if you let the dialog record be allocated in the heap when you created the dialog (by passing NIL as the dStorage parameter to NewDialog or GetNewDialog). æKY DisposeDialog æFc Dialogs.h æT Function æTN A983 æD pascal void DisposeDialog(DialogPtr theDialog) = 0xA983; æDT DisposeDialog((DialogPtr) theDialog); æRI I-415 æC DisposDialog calls CloseDialog (above) and then releases the memory occupied by the dialog’s item list and dialog record. Call DisposDialog when you’re done with a dialog if you let the dialog record be allocated in the heap when you created the dialog (by passing NIL as the dStorage parameter to NewDialog or GetNewDialog). æKY CouldDialog æFc Dialogs.h æT Function æTN A979 æD pascal void CouldDialog(short dialogID) = 0xA979; æDT CouldDialog((short) dialogID); æMM æRI I-415, V-284 æC CouldDialog makes the dialog template having the given resource ID unpurgeable (reading it into memory if it’s not already there). It does the same for the dialog window’s definition function, the dialog’s item list resource, and any items defined as resources. This is useful if the dialog box may come up when the resource file isn’t accessible, such as during a disk copy. Warning: CouldDialog assumes your dialogs use the system font; if you’ve changed the font with SetDAFont, calling CouldDialog doesn’t make the font unpurgeable. The CouldDialog procedure makes the dialog color table template unpurgeable (reading it into memory if it isn’t already there), if it exists. It does the same for the dialog’s color item list, if it has one. Warning: CouldDialog doesn’t load or make 'FONT' or 'FOND' resources indicated in the color item list unpurgeable. æKY FreeDialog æFc Dialogs.h æT Function æTN A97A æD pascal void FreeDialog(short dialogID) = 0xA97A; æDT FreeDialog((short) dialogID); æMM æRI I-415, V-284 æC Given the resource ID of a dialog template previously specified in a call to CouldDialog, FreeDialog undoes the effect of CouldDialog (by making the resources purgeable). It should be called when there’s no longer a need to keep the resources in memory. Given the resource ID of a dialog template previously specified in a call to CouldDialog, the FreeDialog routine undoes the effect of CouldDialog, by restoring the original purge state of the color table and color item list resources. æKY ParamText æFc Dialogs.h æT Function æTN A98B æD pascal void ParamText(ConstStr255Param param0,ConstStr255Param param1,ConstStr255Param param2, ConstStr255Param param3) = 0xA98B; æDT ParamText((ConstStr255Param) param0,(ConstStr255Param) param1,(ConstStr255Param) param2,() ConstStr255Param param3); æMM æRI I-421 æC ParamText provides a means of substituting text in statText items: param0 through param3 will replace the special strings '^0' through '^3' in all statText items in all subsequent dialog or alert boxes. Pass empty strings for parameters not used. Assembly-language note: Assembly-language programmers may pass NIL for parameters not used or for strings that are not to be changed. For example, if the text is defined as 'Cannot open document ^0' and docName is a string variable containing a document name that the user typed, you can call ParamText(docName,' ',' ',' ') Note: All strings that may need to be translated to other languages should be stored in resource files. Assembly-language note: The Dialog Manager stores handles to the four ParamText parameters in a global array named DAStrings. æKY ModalDialog æFc Dialogs.h æT Function æTN A991 æD pascal void ModalDialog(ModalFilterProcPtr filterProc,short *itemHit) = 0xA991; æDT ModalDialog((ModalFilterProcPtr) filterProc,(short *) itemHit); æMM æRT 34, 203 æRI I-415, N34-2, 3, P-108, 176 æC Call ModalDialog after creating a modal dialog and bringing up its window in the frontmost plane. ModalDialog repeatedly gets and handles events in the dialog’s window; after handling an event involving an enabled dialog item, it returns with the item number in itemHit. Normally you’ll then do whatever is appropriate as a response to an event in that item. ModalDialog gets each event by calling the Toolbox Event Manager function GetNextEvent. If the event is a mouse-down event outside the content region of the dialog window, ModalDialog emits sound number 1 (which should be a single beep) and gets the next event; otherwise, it filters and handles the event as described below. Note: Once before getting each event, ModalDialog calls SystemTask, a Desk Manager procedure that must be called regularly so that desk accessories will work properly. The filterProc parameter determines how events are filtered. If it’s NIL, the standard filterProc function is executed; this causes ModalDialog to return 1 in itemHit if the Return key or Enter key is pressed. If filterProc isn’t NIL, ModalDialog filters events by executing the function it points to. Your filterProc function should have three parameters and return a Boolean value. For example, this is how it would be declared if it were named MyFilter: FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent: EventRecord; VAR itemHit: INTEGER) : BOOLEAN; A function result of FALSE tells ModalDialog to go ahead and handle the event, which either can be sent through unchanged or can be changed to simulate a different event. A function result of TRUE tells ModalDialog to return immediately rather than handle the event; in this case, the filterProc function sets itemHit to the item number that ModalDialog should return. Note: If you want it to be consistent with the standard filterProc function, your function should at least check whether the Return key or Enter key was pressed and, if so, return 1 in itemHit and a function result of TRUE. You can use the filterProc function, for example, to treat a typed character in a special way (such as ignore it, or make it have the same effect as another character or as clicking a button); in this case, the function would test for a key-down event with that character. As another example, suppose the dialog box contains a userItem whose procedure draws a clock with the current time displayed. The filterProc function can call that procedure and return FALSE without altering the current event. Note: ModalDialog calls GetNextEvent with a mask that excludes disk-inserted events. To receive disk-inserted events, your filterProc function can call GetNextEvent (or EventAvail) with a mask that accepts only that type of event. ModalDialog handles the events for which the filterProc function returns FALSE as follows: • In response to an activate or update event for the dialog window, ModalDialog activates or updates the window. • If the mouse button is pressed in an editText item, ModalDialog responds to the mouse activity as appropriate (displaying an insertion point or selecting text). If a key-down event occurs and there’s an editText item, text entry and editing are handled in the standard way for such items (except that if the Command key is down, ModalDialog responds as though it’s not). In either case, ModalDialog returns if the editText item is enabled or does nothing if it’s disabled. If a key-down event occurs when there’s no editText item, ModalDialog does nothing. • If the mouse button is pressed in a control, ModalDialog calls the Control Manager function TrackControl. If the mouse button is released inside the control and the control is enabled, ModalDialog returns; otherwise, it does nothing. • If the mouse button is pressed in any other enabled item in the dialog box, ModalDialog returns. If the mouse button is pressed in any other disabled item or in no item, or if any other event occurs, ModalDialog does nothing. æKY IsDialogEvent æFc Dialogs.h æT Function æTN A97F æD pascal Boolean IsDialogEvent(const EventRecord *theEvent) = 0xA97F; æDT Boolean myVariable = IsDialogEvent((const EventRecord *) theEvent); æRI I-416, N5-1, P-108, 175 æC If your application includes any modeless dialogs, call IsDialogEvent after calling the Toolbox Event Manager function GetNextEvent. Warning: If your modeless dialog contains any editText items, you must call IsDialogEvent (and then DialogSelect) even if GetNextEvent returns FALSE; otherwise your dialog won’t receive null events and the caret won’t blink. Pass the current event in theEvent. IsDialogEvent determines whether theEvent needs to be handled as part of a dialog. If theEvent is an activate or update event for a dialog window, a mouse-down event in the content region of an active dialog window, or any other type of event when a dialog window is active, IsDialogEvent returns TRUE; otherwise, it returns FALSE. When FALSE is returned, just handle the event yourself like any other event that’s not dialog-related. When TRUE is returned, you’ll generally end up passing the event to DialogSelect for it to handle (as described below), but first you should do some additional checking: • DialogSelect doesn’t handle keyboard equivalents of commands. Check whether the event is a key-down event with the Command key held down and, if so, carry out the command if it’s one that applies when a dialog window is active. (If the command doesn’t so apply, do nothing.) • In special cases, you may want to bypass DialogSelect or do some preprocessing before calling it. If so, check for those events and respond accordingly. You would need to do this, for example, if the dialog is to respond to disk-inserted events. For cases other than these, pass the event to DialogSelect for it to handle. æKY DialogSelect æFc Dialogs.h æT Function æTN A980 æD pascal Boolean DialogSelect(const EventRecord *theEvent,DialogPtr *theDialog, short *itemHit) = 0xA980; æDT Boolean myVariable = DialogSelect((const EventRecord *) theEvent,(DialogPtr *) theDialog,( short) * itemHit); æMM æRT 34 æRI I-417, N34-3, P-108, 168 æC You’ll normally call DialogSelect when IsDialogEvent returns TRUE, passing in theEvent an event that needs to be handled as part of a modeless dialog. DialogSelect handles the event as described below. If the event involves an enabled dialog item, DialogSelect returns a function result of TRUE with the dialog pointer in theDialog and the item number in itemHit; otherwise, it returns FALSE with theDialog and itemHit undefined. Normally when DialogSelect returns TRUE, you’ll do whatever is appropriate as a response to the event, and when it returns FALSE you’ll do nothing. If the event is an activate or update event for a dialog window, DialogSelect activates or updates the window and returns FALSE. If the event is a mouse-down event in an editText item, DialogSelect responds as appropriate (displaying a caret at the insertion point or selecting text). If it’s a key-down or auto-key event and there’s an editText item, text entry and editing are handled in the standard way. In either case, DialogSelect returns TRUE if the editText item is enabled or FALSE if it’s disabled. If a key-down or auto-key event is passed when there’s no editText item, DialogSelect returns FALSE. Note: For a keyboard event, DialogSelect doesn’t check to see whether the Command key is held down; to handle keyboard equivalents of commands, you have to check for them before calling DialogSelect. Similarly, to treat a typed character in a special way (such as ignore it, or make it have the same effect as another character or as clicking a button), you need to check for a key-down event with that character before calling DialogSelect. If the event is a mouse-down event in a control, DialogSelect calls the Control Manager function TrackControl. If the mouse button is released inside the control and the control is enabled, DialogSelect returns TRUE; otherwise, it returns FALSE. If the event is a mouse-down event in any other enabled item, DialogSelect returns TRUE. If it’s a mouse-down event in any other disabled item or in no item, or if it’s any other event, DialogSelect returns FALSE. Note: If the event isn’t one that DialogSelect specifically checks for (if it’s a null event, for example), and there’s an editText item in the dialog, DialogSelect calls the TextEdit procedure TEIdle to make the caret blink. æKY DrawDialog æFc Dialogs.h æT Function æTN A981 æD pascal void DrawDialog(DialogPtr theDialog) = 0xA981; æDT DrawDialog((DialogPtr) theDialog); æMM æRI I-418 æC DrawDialog draws the contents of the given dialog box. Since DialogSelect and ModalDialog handle dialog window updating, this procedure is useful only in unusual situations. You would call it, for example, to display a dialog box that doesn’t require any response but merely tells the user what’s going on during a time-consuming process. æKY UpdtDialog æFc Dialogs.h æT Function æTN A978 æD pascal void UpdtDialog(DialogPtr theDialog,RgnHandle updateRgn) = 0xA978; æDT UpdtDialog((DialogPtr) theDialog,(RgnHandle) updateRgn); æMM æRI IV-60 æC UpdtDialog is a faster version of the DrawDialog procedure. Instead of drawing the entire contents of the given dialog box, UpdtDialog draws only the items that are in a specified update region. UpdtDialog is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port. (For more details, see the BeginUpdate procedure in the Window Manager chapter.) æKY UpdateDialog æFc Dialogs.h æT Function æTN A978 æD pascal void UpdateDialog(DialogPtr theDialog,RgnHandle updateRgn) = 0xA978; æDT UpdateDialog((DialogPtr) theDialog,(RgnHandle) updateRgn); æMM æRI IV-60 æC UpdtDialog is a faster version of the DrawDialog procedure. Instead of drawing the entire contents of the given dialog box, UpdtDialog draws only the items that are in a specified update region. UpdtDialog is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port. (For more details, see the BeginUpdate procedure in the Window Manager chapter.) æKY Alert æFc Dialogs.h æT Function æTN A985 æD pascal short Alert(short alertID,ModalFilterProcPtr filterProc) = 0xA985; æDT short myVariable = Alert((short) alertID,(ModalFilterProcPtr) filterProc); æMM æRI I-418, V-284 æC This function invokes the alert defined by the alert template that has the given resource ID. It calls the current sound procedure, if any, passing it the sound number specified in the alert template for this stage of the alert. If no alert box is to be drawn at this stage, Alert returns a function result of –1; otherwise, it creates and displays the alert window for this alert and draws the alert box. Warning: If the alert template resource can’t be read, the function result is undefined. Note: Alert creates the alert window by calling NewDialog, and does the rest of its processing by calling ModalDialog. Alert repeatedly gets and handles events in the alert window until an enabled item is clicked, at which time it returns the item number. Normally you’ll then do whatever is appropriate in response to a click of that item. Alert gets each event by calling the Toolbox Event Manager function GetNextEvent. If the event is a mouse-down event outside the content region of the alert window, Alert emits sound number 1 (which should be a single beep) and gets the next event; otherwise, it filters and handles the event as described below. The filterProc parameter has the same meaning as in ModalDialog (see above). If it’s NIL, the standard filterProc function is executed, which makes the Return key or the Enter key have the same effect as clicking the default button. If you specify your own filterProc function and want to retain this feature, you must include it in your function. You can find out what the current default button is by looking at the aDefItem field of the dialog record for the alert (via the dialog pointer passed to the function). Alert handles the events for which the filterProc function returns FALSE as follows: • If the mouse button is pressed in a control, Alert calls the Control Manager procedure TrackControl. If the mouse button is released inside the control and the control is enabled, Alert returns; otherwise, it does nothing. • If the mouse button is pressed in any other enabled item, Alert simply returns. If it’s pressed in any other disabled item or in no item, or if any other event occurs, Alert does nothing. Before returning to the application with the item number, Alert removes the alert box from the screen. (It disposes of the alert window and its associated data structures, the item list, and the items.) Note: When an alert is removed, if it was overlapping the default button of a previous alert, that button’s bold outline won’t be redrawn. Note: The Alert function’s removal of the alert box would not be the desired result if the user clicked a check box or radio button; however, normally alerts contain only static text, icons, pictures, and buttons that are supposed to make the alert box go away. If your alert contains other items besides these, consider whether it might be more appropriate as a dialog. The Alert function looks for a resource of type 'actb' with the same ID as the alert. The alert color table is copied before it is passed to SetWinSize unless its ctSize field is equal to –1, indicating that the default window colors are to be used instead. The copy is made so that the color table resource can be purged without affecting the alert. The color dialog item list resource is duplicated as well, so it can be purgeable. æKY StopAlert æFc Dialogs.h æT Function æTN A986 æD pascal short StopAlert(short alertID,ModalFilterProcPtr filterProc) = 0xA986; æDT short myVariable = StopAlert((short) alertID,(ModalFilterProcPtr) filterProc); æMM æRI I-419, V-284, P-109, 182 æC StopAlert is the same as the Alert function (above) except that before drawing the items of the alert in the alert box, it draws the Stop icon in the top left corner of the box (within the rectangle (10,20)(42,52)). The Stop icon has the following resource ID: CONST stopIcon = 0; If the application’s resource file doesn’t include an icon with that ID number, the Dialog Manager uses the standard Stop icon in the system resource file (see Figure 11). The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. •••Refer to Figure 11.••• Figure 11–Standard Alert Icons æKY NoteAlert æFc Dialogs.h æT Function æTN A987 æD pascal short NoteAlert(short alertID,ModalFilterProcPtr filterProc) = 0xA987; æDT short myVariable = NoteAlert((short) alertID,(ModalFilterProcPtr) filterProc); æMM æRI I-420 æC NoteAlert is like StopAlert except that it draws the Note icon, which has the following resource ID: CONST noteIcon = 1; The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. æKY CautionAlert æFc Dialogs.h æT Function æTN A988 æD pascal short CautionAlert(short alertID,ModalFilterProcPtr filterProc) = 0xA988; æDT short myVariable = CautionAlert((short) alertID,(ModalFilterProcPtr) filterProc); æMM æRI I-420 æC CautionAlert is like StopAlert except that it draws the Caution icon, which has the following resource ID: CONST cautionIcon = 2; The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. æKY CouldAlert æFc Dialogs.h æT Function æTN A989 æD pascal void CouldAlert(short alertID) = 0xA989; æDT CouldAlert((short) alertID); æMM æRI I-420, V-285 æC CouldAlert makes the alert template having the given resource ID unpurgeable (reading it into memory if it’s not already there). It does the same for the alert window’s definition function, the alert’s item list resource, and any items defined as resources. This is useful if the alert may occur when the resource file isn’t accessible, such as during a disk copy. Warning: Like CouldDialog, CouldAlert assumes your alerts use the system font; if you’ve changed the font with SetDAFont, calling CouldAlert doesn’t make the font unpurgeable. The CouldAlert routine makes the alert color table template unpurgeable (reading it into memory if it isn’t already there), if it exists. It does the same for the alert’s color item list, if it has one. Warning: Like CouldDialog, CouldAlert doesn’t load or make 'FONT' or 'FOND' resources indicated in the color item list unpurgeable. æKY FreeAlert æFc Dialogs.h æT Function æTN A98A æD pascal void FreeAlert(short alertID) = 0xA98A; æDT FreeAlert((short) alertID); æMM æRI I-420, V-285 æC Given the resource ID of an alert template previously specified in a call to CouldAlert, FreeAlert undoes the effect of CouldAlert (by making the resources purgeable). It should be called when there’s no longer a need to keep the resources in memory. Given the resource ID of an alert template previously specified in a call to CouldAlert, the FreeAlert routine undoes the effect of CouldAlert, by restoring the original purge state of the color table and color item list resources. æKY GetDItem æFc Dialogs.h æT Function æTN A98D æD pascal void GetDItem(DialogPtr theDialog,short itemNo,short *itemType,Handle *item, Rect *box) = 0xA98D; æDT GetDItem((DialogPtr) theDialog,(short) itemNo,(short *) itemType,(Handle *) item,( Rect) * box); æMM æRI I-421 æC GetDItem returns in its VAR parameters the following information about the item numbered itemNo in the given dialog’s item list: In the itemType parameter, the item type; in the item parameter, a handle to the item (or, for item type userItem, the procedure pointer); and in the box parameter, the display rectangle for the item. Suppose, for example, that you want to change the title of a control in a dialog box. You can get the item handle with GetDItem, coerce it to type ControlHandle, and call the Control Manager procedure SetCTitle to change the title. Similarly, to move the control or change its size, you would call MoveControl or SizeControl. Note: To access the text of a statText or editText item, you can pass the handle returned by GetDItem to GetIText or SetIText (see below). æKY SetDItem æFc Dialogs.h æT Function æTN A98E æD pascal void SetDItem(DialogPtr theDialog,short itemNo,short itemType,Handle item, const Rect *box) = 0xA98E; æDT SetDItem((DialogPtr) theDialog,(short) itemNo,(short) itemType,(Handle) item,( const Rect) * box); æMM æRT 34 æRI I-421, N34-1 æC SetDItem sets the item numbered itemNo in the given dialog’s item list, as specified by the parameters (without drawing the item). The itemType parameter is the item type; the item parameter is a handle to the item (or, for item type userItem, the procedure pointer); and the box parameter is the display rectangle for the item. Consider, for example, how to install an item of type userItem in a dialog: In the item list in the resource file, define an item in which the type is set to userItem and the display rectangle to (0,0)(0,0). Specify that the dialog window be invisible (in either the dialog template or the NewDialog call). After creating the dialog, coerce the item’s procedure pointer to type Handle; then call SetDItem, passing that handle and the display rectangle for the item. Finally, call the Window Manager procedure ShowWindow to display the dialog window. Note: Do not use SetDItem to change the text of a statText or editText item or to change or move a control. See the description of GetDItem above for more information. æKY HideDItem æFc Dialogs.h æT Function æTN A827 æD pascal void HideDItem(DialogPtr theDialog,short itemNo) = 0xA827; æDT HideDItem((DialogPtr) theDialog,(short) itemNo); æMM æRI IV-59 æC HideDItem hides the item numbered itemNo in the given dialog’s item list by giving the item a display rectangle that’s off the screen. (Specifically, if the left coordinate of the item’s display rectangle is less than 8192, ShowDItem adds 16384 to both the left and right coordinates the rectangle.) If the item is already hidden (that is, if the left coordinate is greater than 8192), HideDItem does nothing. HideDItem calls the EraseRect procedure on the item’s enclosing rectangle and adds the rectangle that contained the item (not necessarily the item’s display rectangle) to the update region. If the specified item is an active editText item, the item is first deactivated (by calling TEDeactivate). Note: If you have items that are close to each other, be aware that the Dialog Manager draws outside of the enclosing rectangle by 3 pixels for editText items and by 4 pixels for a default button. An item that’s been hidden by HideDItem can be redisplayed by the ShowDItem procedure. Note: To create a hidden item in a dialog item list, simply add 16384 to the left and right coordinates of the display rectangle. æKY ShowDItem æFc Dialogs.h æT Function æTN A828 æD pascal void ShowDItem(DialogPtr theDialog,short itemNo) = 0xA828; æDT ShowDItem((DialogPtr) theDialog,(short) itemNo); æMM æRI IV-59 æC ShowDItem redisplays the item numbered itemNo, previously hidden by HideDItem, by giving the item the display rectangle it had prior to the HideDItem call. (Specifically, if the left coordinate of the item’s display rectangle is greater than 8192, ShowDItem subtracts 16384 from both the left and right coordinates of the rectangle.) If the item is already visible (that is, if the left coordinate is less than 8192), ShowDItem does nothing. ShowDItem adds the rectangle that contained the item (not necessarily the item’s display rectangle) to the update region so that it will be drawn. If the item becomes the only editText item, ShowDItem activates it (by calling TEActivate). æKY SelIText æFc Dialogs.h æT Function æTN A97E æD pascal void SelIText(DialogPtr theDialog,short itemNo,short strtSel,short endSel) = 0xA97E; æDT SelIText((DialogPtr) theDialog,(short) itemNo,(short) strtSel,(short) endSel); æMM æRI I-422, P-110 æC Given a pointer to a dialog and the item number of an editText item in the dialog box, SelIText does the following: • If the item contains text, SelIText sets the selection range to extend from character position strtSel up to but not including character position endSel. The selection range is inverted unless strtSel equals endSel, in which case a blinking vertical bar is displayed to indicate an insertion point at that position. • If the item doesn’t contain text, SelIText simply displays the insertion point. For example, if the user makes an unacceptable entry in the editText item, the application can put up an alert box reporting the problem and then select the entire text of the item so it can be replaced by a new entry. (Without this procedure, the user would have to select the item before making the new entry.) Note: You can select the entire texxt by specifying 0 for strtSel and 32767 for endSel. For details about selection range and character position, see the TextEdit chapter. æKY GetIText æFc Dialogs.h æT Function æTN A990 æD pascal void GetIText(Handle item,Str255 text) = 0xA990; æDT GetIText((Handle) item,(Str255) text); æRT 18 æRI I-422, N18-2 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, GetIText returns the text of the item in the text parameter. (If the user typed more than 255 characters in an editText item, GetIText returns only the first 255.) æKY SetIText æFc Dialogs.h æT Function æTN A98F æD pascal void SetIText(Handle item,ConstStr255Param text) = 0xA98F; æDT SetIText((Handle) item,(ConstStr255Param) text); æMM æRI I-422 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, SetIText sets the text of the item to the specified text and draws the item. For example, suppose the exact content of a dialog’s text item cannot be determined until the application is running, but the display rectangle is defined in the resource file: Call GetDItem to get a handle to the item, and call SetIText with the desired text. æKY FindDItem æFc Dialogs.h æT Function æTN A984 æD pascal short FindDItem(DialogPtr theDialog,Point thePt) = 0xA984; æDT short myVariable = FindDItem((DialogPtr) theDialog,(Point) thePt); æMM æRT 112 æRI IV-60, N112 æC FindDItem returns the item number of the item containing the point specified, in local coordinates, by thePt. If the point doesn’t lie within the item’s rectangle, FindDItem returns –1. If there are overlapping items, it returns the item number of the first item in the list containing the point. FindDItem is useful for changing the cursor when it’s over a particular item. Note: FindDItem will return the item number of disabled items as well. æKY NewCDialog æFc Dialogs.h æT Function æTN AA4B æD pascal DialogPtr NewCDialog(void *dStorage,const Rect *boundsRect,ConstStr255Param title, Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon, Handle items) = 0xAA4B; æDT DialogPtr myVariable = NewCDialog((void *) dStorage,(const Rect *) boundsRect,(ConstStr255Param) title,() Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,() Handle items); æMM æRI V-283 æC A new Dialog Manager routine has been added to support color dialogs: NewCDialog. Its parameters are identical to NewDialog, except that a cGrafPort is allocated through a NewCWindow call instead of a call to NewWindow. NewCDialog creates a dialog box as specified by its parameters and returns a cDialogPtr to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewCWindow, which creates the dialog window. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. After calling NewCDialog, you can use SetWinColor to add a color table to the dialog. This creates an auxiliary window record (auxWinRec) for the dialog window. You can access this record with the GetAuxWin routine. The dialogCItem handle within the auxWinRec points to the dialog item color table. If the dialog’s content color isn’t white, it’s a good idea to call NewCDialog with the visible flag set to FALSE. After the color table and color item list are installed, use ShowWindow to display the dialog if the dialog is the frontmost window. If the dialog is not in front, use ShowHide to display the dialog. æKY newcdialog æFc Dialogs.h æT Function æD DialogPtr newcdialog(void *dStorage,const Rect *boundsRect,char *title, Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon, Handle items); æDT DialogPtr myVariable = newcdialog((void *) dStorage,(const Rect *) boundsRect,(char *) title,() Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,() Handle items); æRI V-283 æC A new Dialog Manager routine has been added to support color dialogs: NewCDialog. Its parameters are identical to NewDialog, except that a cGrafPort is allocated through a NewCWindow call instead of a call to NewWindow. NewCDialog creates a dialog box as specified by its parameters and returns a cDialogPtr to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewCWindow, which creates the dialog window. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. After calling NewCDialog, you can use SetWinColor to add a color table to the dialog. This creates an auxiliary window record (auxWinRec) for the dialog window. You can access this record with the GetAuxWin routine. The dialogCItem handle within the auxWinRec points to the dialog item color table. If the dialog’s content color isn’t white, it’s a good idea to call NewCDialog with the visible flag set to FALSE. After the color table and color item list are installed, use ShowWindow to display the dialog if the dialog is the frontmost window. If the dialog is not in front, use ShowHide to display the dialog. æKY GetAlrtStage æFc Dialogs.h æT Function æD #define GetAlrtStage() (* (short*) 0x0A9A) æDT #define myVariable = GetAlrtStage(); æRI I-422 æC GetAlrtStage returns the stage of the last occurrence of an alert, as a number from 0 to 3. Assembly-language note: Assembly-language programmers can get this number by accessing the global variable ACount. In addition, the global variable ANumber contains the resource ID of the alert template of the last alert that occurred. æKY ResetAlrtStage æFc Dialogs.h æT Function æD pascal void ResetAlrtStage(void) = {0x4278,0x0A9A}; æDT ResetAlrtStage()(void); æRI I-423 æC ResetAlrtStage resets the stage of the last occurrence of an alert so that the next occurrence of that same alert will be treated as its first stage. This is useful, for example, when you’ve used ParamText to change the text of an alert such that from the user’s point of view it’s a different alert. Assembly-language note: Assembly-language programmers can set the global variable ACount to –1 for the same effect. æKY DlgCut æFc Dialogs.h æT Function æD pascal void DlgCut(DialogPtr theDialog); æDT DlgCut((DialogPtr) theDialog); æRT 215 æRI I-418, P-110 æC [Not in ROM] DlgCut checks whether theDialog has any editText items and, if so, applies the TextEdit procedure TECut to the currently selected editText item. (If the dialog record’s editField is 0 or greater, DlgCut passes the contents of the textH field to TECut.) You can call DlgCut to handle the editing command Cut when a modeless dialog window is active. Assembly-language note: Assembly-language programmers can just read the dialog record’s fields and call TextEdit directly. æKY DlgPaste æFc Dialogs.h æT Function æD pascal void DlgPaste(DialogPtr theDialog); æDT DlgPaste((DialogPtr) theDialog); æMM æRT 215 æRI I-418, P-110 æC [Not in ROM] DlgPaste is the same as DlgCut (above) except that it calls TEPaste, for handling the Paste command. æKY DlgCopy æFc Dialogs.h æT Function æD pascal void DlgCopy(DialogPtr theDialog); æDT DlgCopy((DialogPtr) theDialog); æMM æRT 215 æRI I-418, P-110 æC [Not in ROM] DlgCopy is the same as DlgCut (above) except that it calls TECopy, for handling the Copy command. æKY DlgDelete æFc Dialogs.h æT Function æD pascal void DlgDelete(DialogPtr theDialog); æDT DlgDelete((DialogPtr) theDialog); æMM æRT 215 æRI I-418, P-110 æC [Not in ROM] DlgDelete is the same as DlgCut (above) except that it calls TEDelete, for handling the Clear command. æKY SetDAFont æFc Dialogs.h æT Function æD pascal void SetDAFont(short fontNum) = {0x31DF,0x0AFA}; æDT SetDAFont((short) fontNum); æRI I-412 æC For subsequently created dialogs and alerts, SetDAFont causes the font of the dialog or alert window’s grafPort to be set to the font having the specified font number. If you don’t call this procedure, the system font is used. SetDAFont affects statText and editText items but not titles of controls, which are always in the system font. Assembly-language note: Assembly-language programmers can simply set the global variable DlgFont to the desired font number. æKY paramtext æFc Dialogs.h æT Function æD void paramtext(char *param0,char *param1,char *param2,char *param3); æDT paramtext((char *) param0,(char *) param1,(char *) param2,(char *) param3); æMM æRI I-421 æC ParamText provides a means of substituting text in statText items: param0 through param3 will replace the special strings '^0' through '^3' in all statText items in all subsequent dialog or alert boxes. Pass empty strings for parameters not used. Assembly-language note: Assembly-language programmers may pass NIL for parameters not used or for strings that are not to be changed. For example, if the text is defined as 'Cannot open document ^0' and docName is a string variable containing a document name that the user typed, you can call ParamText(docName,' ',' ',' ') Note: All strings that may need to be translated to other languages should be stored in resource files. Assembly-language note: The Dialog Manager stores handles to the four ParamText parameters in a global array named DAStrings. æKY getitext æFc Dialogs.h æT Function æD void getitext(Handle item,char *text); æDT getitext((Handle) item,(char *) text); æRT 18 æRI I-422, N18-2 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, GetIText returns the text of the item in the text parameter. (If the user typed more than 255 characters in an editText item, GetIText returns only the first 255.) æKY setitext æFc Dialogs.h æT Function æD void setitext(Handle item,char *text); æDT setitext((Handle) item,(char *) text); æMM æRI I-422 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, SetIText sets the text of the item to the specified text and draws the item. For example, suppose the exact content of a dialog’s text item cannot be determined until the application is running, but the display rectangle is defined in the resource file: Call GetDItem to get a handle to the item, and call SetIText with the desired text. æKY findditem æFc Dialogs.h æT Function æD short findditem(DialogPtr theDialog,Point *thePt); æDT short myVariable = findditem((DialogPtr) theDialog,(Point *) thePt); æRI IV-60, N112 æC FindDItem returns the item number of the item containing the point specified, in local coordinates, by thePt. If the point doesn’t lie within the item’s rectangle, FindDItem returns –1. If there are overlapping items, it returns the item number of the first item in the list containing the point. FindDItem is useful for changing the cursor when it’s over a particular item. Note: FindDItem will return the item number of disabled items as well. æKY DisAsmLookup.h æKL Disassembler endOfModule InitLookup Lookup LookupTrapName ModifyOperand showMacsBugSymbol validMacsBugSymbol _A0_ _A1_ _A2_ _A3_ _A4_ _A5_ _A6_ _A7_ _ABS_ _PC_ _TRAP_ LookupRegs æKY Disassembler æFc DisAsmLookup.h æT Function æD pascal void Disassembler(long DstAdjust,short *BytesUsed,Ptr FirstByte, char *Opcode,char *Operand,char *Comment,Ptr LookUpProc); æDT Disassembler((long)DstAdjust,(short *)BytesUsed,(Ptr)FirstByte, (char *)Opcode,(char *)Operand,(char *)Comment,(Ptr)LookUpProc); æC /* Disassembler is a Pascal routine to be called to disassemble a sequence of bytes. All MC68xxx, MC68881, and MC68851 instructions are supported. The sequence of bytes to be disassembled are pointed to by FirstByte. BytesUsed bytes starting at FirstByte are consumed by the disassembly, and the Opcode, Operand, and Comment strings returned as NULL TERMINATED Pascal strings (for easier manipulation with C). The caller is then free to format or use the output strings any way appropriate to the application. Depending on the opcode and effective address(s) (EA's) to be disassembled, the Opcode, Operand, and Comment strings contain the following information: Case Opcode Operand Comment ======================================================================= Non PC-relative EA's op.sz EA's PC-relative EA's op.sz EA's ; address Toolbox traps DC.W $AXXX ; TB XXXX OS traps DC.W $AXXX ; OS XXXX Invalid bytes DC.W $XXXX ; ???? Invalid byte #immediate DC.W $XXXX,... ; op.sz #$??XX,EA ======================================================================= For valid disassembly of processor instructions the appropriate MC68XXX opcode mnemonic is generated for the Opcode string along with a size attribute when required. The source and destination EA's are generated as the Operand along with a possible comment. Comments start with a ';'. Traps use a DC.W assembler directive as the Opcode with the trap word as the Operand and a comment indicating whether the trap is a toolbox or OS trap and what the trap number is. As described later the caller can generate symbolic substitutions into EA's and provide names for traps. Invalid instructions cause the string 'DC.W' to be returned in the Opcode string. Operand is '$XXXX' (the invalid word) with a comment of '; ????'. BytesUsed is 2. This is similar to the trap call case except for the comment. A special case is made for immediate byte operands with a nonzero high order byte. For example, the bytes $020011FF, when actually executed, would be interpreted as ANDI.B $FF,D0. The processor will IGNORE the high order byte of the immediate data! Thus, the bytes may be considered as valid. Since the Disassembler has no way of knowing the context in which it is disassembling, it returns the Opcode as 'DC.W' as in the normal invalid case. However, the Operand string shows ALL the words disassembled separated with commas and places the possibly valid disassembly in the Operand's comment indicating the nonzero bytes. Thus for the example $020011FF bytes, the Opcode will be 'DC.W', the Operand will be '$0200,$11FF', and the Comment '; ANDI.B #$??FF,D0'. BytesUsed in this case would be 4. Note, the Operand EA's is syntatically similar to but NOT COMPATIBLE with the MPW assembler! This is because the Disassembler generates byte hex constants as "$XX" and word hex constants as "$XXXX". Negative values (e.g., $FF or $FFFF) produced by the Disassembler are treated as long word values by the MPW assembler. Thus it is assumed that Disassembler output will NOT be used as MPW assembler input. If that is the goal, then the caller must convert strings of the form $XX or $XXXX in the Operand string to their decimal equivalent. The routine ModifyOperand is provided in this unit to aid with the conversion process. Since a PC-relative comment is an address, the only address that the Disassembler knows about is the address of the code pointed to by FirstByte. Generally, that may be a buffer that has no relation to "reality", i.e., the actual code loaded into the buffer. Therefore, to allow the address comment to be mapped back to some actual address the caller may specify an adjustment factor, specified by DstAdjust that is ADDED to the value that normally would be placed in the comment. Operand effective address strings are generated as a function of the effective address mode and a special case is made for A-trap opcode strings. In places where a possible symbolic reference could be substituted for an address (or a portion of an address), the Disassembler can call a user specified routine to do the substitution (using th LookupProc parameter described later). The following table summarizes the generated effective addresses and where symbolic substitutions (S) can be made: Mode Generated Effective Address Effective Address with Substitution ======================================================================== 0 Dn Dn 1 An An 2 (An) (An) 3 (An)+ (An)+ 4 -(An) -(An) 5 ∂(An) S(An) or just S (if An=A5, ∂≥0) 6n ∂(An,Xn.Size*Scale) S(An,Xn.Size*Scale) 6n (BD,An,Xn.Size*Scale) (S,An,Xn.Size*Scale) 6n ([BD,An],Xm.Size*Scale,OD) ([S,An],Xm.Size*Scale,OD) 6n ([BD,An,Xn.Size*Scale],OD) ([S,An,Xn.Size*Scale],OD) 70 ∂ S 71 ∂ S 72 *±∂ S 73 *±∂(Xn.Size*Scale) S(Xn.Size*Scale) 73 (*±∂,Xn.Size*Scale) (S,Xn.Size*Scale) 73 ([*±∂],Xm.Size*Scale,OD) ([S],Xm.Size*Scale,OD) 73 ([*±∂,Xn.Size*Scale],OD) ([S,Xn.Size*Scale],OD) 74 #data #data ======================================================================== For A-traps, the substitution can be performed to substitute for the DC.W opcode string. If the substitution is made then the Disassembler will generate ,Sys and/or ,Immed flags as operands for Toolbox traps and ,AutoPop for OS traps when the bits in the trap word indicates these settings. | Generated | Substituted | Opcode Operand Comment | Opcode Operand Comment ======================================================================== Toolbox | DC.W $AXXX ; TB XXXX | S [,Sys][,Immed] ; AXXX OS | DC.W $AXXX ; OS XXXX | S [,AutoPop] ; AXXX ======================================================================== All displacements (∂, BD, OD) are hexadecimal values shown as a byte ($XX), word ($XXXX), or long ($XXXXXXXX) as appropriate. The *Scale is suppressed if 1. The Size is W or L. Note that effective address substitutions can only be made for "∂(An)", "BD,An", and "*±∂" cases. For all the effective address modes 5, 6n, 7n, and for A-traps, a coroutine (a procedure) whose address is specified by the LookupProc parameter is called by the Disassembler (if LookupProc is not NIL) to do the substitution (or A-trap comment) with a string returned by the proc. It is assumed that the proc pointed to by LookupProc is a level 1 Pascal proc declared as follows: PROCEDURE Lookup( PC: UNIV Ptr; {Addr of extension/trap word} BaseReg: LookupRegs; {Base register/lookup mode } Opnd: UNIV LongInt; {Trap word, PC addr, disp. } VAR S: DisAsmStr80); {Returned substitution } where TYPE DisAsmStr80 = String[80]; or in C, pascal void LookUp(Ptr PC, LookupRegs BaseReg, long Opnd, char *S); PC = Pointer to instruction extension word or A-trap word in the buffer pointed to by the Disassembler's FirstByte parameter. BaseReg = This determines the meaning of the Opnd value and supplies the base register for the "∂(An)", "BD,An", and "*±∂" cases. BaseReg may contain any one of the following values: _A0_ = 0 ==> A0 _A1_ = 1 ==> A1 _A2_ = 2 ==> A2 _A3_ = 3 ==> A3 _A4_ = 4 ==> A4 _A5_ = 5 ==> A5 _A6_ = 6 ==> A6 _A7_ = 7 ==> A7 _PC_ = 8 ==> PC-relative (special case) _ABS_ = 9 ==> Abs addr (special case) _TRAP_ = 10 ==> Trap word (special case) For absolute addressing (modes 70 and 71), BaseReg contains _ABS_. For A-traps, BaseReg would contain _TRAP_. Opnd = The contents of this LongInt is determined by the BaseReg parameter just described. For BaseReg = _TRAP_ (A-traps): Opnd is the entire trap word. The high order 16 bits of Opnd are zero. For BaseReg = _ABS_ (absolute effective address): Opnd contains the (extended) 32-bit address specifed by the instruction's effective address. Such addresses would generally be used to reference low memory globals on a Macintosh. For BaseReg = _PC_ (PC-relative effective address): Opnd contains the 32-bit address represented by "*±∂" adjusted by the Disassembler's DstAdjust parameter. For BaseReg = _An_ (effective address with a base register): Opnd contains the (sign-extended) 32-bit (base) displacement from the instruction's effective address. In the Macintosh environment, a BaseReg specifying A5 implies either global data references or Jump Table references. Positive Opnd values with an A5 BaseReg thus mean Jump Table references, while a negative offset would mean a global data reference. Base registers of A6 or A7 would usually mean local data. S = Pascal string returned from Lookup containing the effective address substitution string or a trap name for A-traps. S is set to null PRIOR to calling Lookup. If it is still null on return, the string is not used. If not null, then for A-traps, the returned string is used as a opcode string. In all other cases the string is substituted as shown in the above table. Depending on the application, the caller has three choices on how to use the Disassembler and an associated Lookup proc: (1). The caller can call just the Disassembler and provide his own Lookup proc. In that case the calling conventions discussed above must be followed. (2). The caller can provide NIL for the LookupProc parameter, in which case, NO Lookup proc will be called. (3). The caller can call first InitLookup (described below, a proc provided with this unit) and pass the address of this unit's standard Lookup proc when Disassembler is called. In this case all the control logic to determine the kind of substitution to be done is provided for the caller and all that need to be provided by the user are routines to look up any or all of the following: • PC-relative references • Jump Table references • Absolute address references • Trap names • References with offsets from base registers */ æKY endOfModule æFc DisAsmLookup.h æT Function æD char *endOfModule(void *address,void *limit,char *symbol,void **nextModule); æDT char myVariable = endOfModule((void *)address,(void *)limit,(char *)symbol, (void *)*nextModule); æC /* Check to see if the specified memory address, contains a RTS, JMP (A0) or RTD #n instruction immediately followed by a valid MacsBug symbol. These sequences are the only ones which can determine an end of module when MacsBug symbols are present. During the check, the instruction and its following MacsBug symbol must be fully contained in the bytes starting at the specified address parameter, up to, but not including, the byte pointed to by the limit parameter. If the end of module is NOT found, then NULL is returned as the function's result. However, if a end of module is found, the MacsBug symbol is returned in symbol (if it is not NULL) as a null terminated Pascal string (with trailing blanks removed), and the functions returns the pointer to the start of the MacsBug symbol (i.e., address+2 for RTS or JMP (A0) and address+4 for RTD #n). This address may then be used as in input parameter to showMacsBugSymbol to convert the MacsBug symbol to a Disassembler operand string. Also returned in nextModule is where we think the FOLLOWING module begins. In the "old style" cases (see validMacsBugSymbol) this will always be 8 or 16 bytes after the input address. For new style the Apple Pascal and C cases this will depend on the symbol length, existence of a pad byte, and size of the constant (literal) area. See validMacsBugSymbol for a description of valid MacsBug symbol formats. */ æKY InitLookup æFc DisAsmLookup.h æT Function æD pascal void InitLookup(Ptr PCRelProc,Ptr JTOffProc,Ptr TrapProc,Ptr AbsAddrProc, Ptr IdProc); æDT InitLookup((Ptr)PCRelProc,(Ptr)JTOffProc,(Ptr)TrapProc, (Ptr)AbsAddrProc,(Ptr)IdProc); æC /* Prepare for use of this unit's Lookup proc. When Disassembler is called and the address of this unit's Lookup proc is specified, then for PC-relative, Jump Table references, A-traps, absolute addresses, and offsets from a base register, the associated level 1 Pascal proc specified here is called (if not NULL -- all five addresses are preset to NULL). The calls assume the following declarations for these procs (see Lookup, below for further details): PROCEDURE PCRelProc(Address: UNIV LongInt; VAR S: UNIV DisAsmStr80); PROCEDURE JTOffProc(A5JTOffset: UNIV Integer; VAR S: UNIV DisAsmStr80); PROCEDURE TrapNameProc(TrapWord: UNIV Integer; VAR S: UNIV DisAsmStr80); PROCEDURE AbsAddrProc(AbsAddr: UNIV LongInt; VAR S: UNIV DisAsmStr80); PROCEDURE IdProc(BaseReg: LookupRegs; Offset: UNIV LongInt; VAR S: UNIV DisAsmStr80); or in C, pascal void PCRelProc(long Address, char *S) pascal void JTOffProc(short A5JTOffset, char *S) pascal void TrapNameProc(unsigned short TrapWord, char *S) pascal void AbsAddrProc(long AbsAddr, char *S) pascal void IdProc(LookupRegs BaseReg, long Offset, char *S) Note: InitLookup contains initialized data which requires initializing at load time (this is of concern only to users with assembler main programs. */ æKY Lookup æFc DisAsmLookup.h æT Function æD pascal void Lookup(Ptr PC,LookupRegs BaseReg,long Opnd,char *S); æDT Lookup((Ptr)PC,(LookupRegs)BaseReg,(long)Opnd,(char *)S); æC /* This is a standard Lookup proc available to the caller for calls to the Disassembler. If the caller elects to use this proc, then InitLookup MUST be called prior to any calls to the Disassembler. All the logic to determine the type of lookup is done by this proc. For PC-relative, Jump Table references, A-traps, absolute addresses, and offsets from a base register, the associated level 1 Pascal proc specified in the InitLookup call (if not NULL) is called. This scheme simplifies the Lookup mechanism by allowing the caller to deal with just the problems related to the application. */ æKY LookupRegs _A0_ _A1_ _A2_ _A3_ _A4_ _A5_ _A6_ _A7_ _PC_ _ABS_ _TRAP_ æFc DisAsmLookup.h æD enum {_A0_,_A1_,_A2_,_A3_,_A4_,_A5_,_A6_,_A7_,_PC_,_ABS_,_TRAP_}LookupRegs; typedef unsigned char LookupRegs; æKY LookupTrapName æFc DisAsmLookup.h æT Function æD pascal void LookupTrapName(unsigned short TrapWord,char *S); æDT LookupTrapName((unsigned short)TrapWord,(char *)S); æC /* This is a procedure provided to allow conversion of a trap instruction (in TrapWord) to its corresponding trap name (in S). It is provided primarily for use with the Disassembler and its address may be passed to InitLookup above for use by this unit's Lookup routine. Alternatively, there is nothing prohibiting the caller from using it directly for other purposes or by some other lookup proc. Note: The tables in this proc make the size of this proc about 9500 bytes. The trap names are fully spelled out in upper and lower case. */ æKY ModifyOperand æFc DisAsmLookup.h æT Function æD pascal void ModifyOperand(char *operand); æDT ModifyOperand((char *)operand); æC /* Scan an operand string, i.e., the null terminated Pascal string returned by the Disassembler (null MUST be present here) and modify negative hex values to negated positive value. For example, $FFFF(A5) would be modified to -$0001(A5). The operand to be processed is passed as the function's parameter which is edited "in place" and returned to the caller. This routine is essentially a pattern matcher and attempts to only modify 2, 4, and 8 digit hex strings in the operand that "might" be offsets from a base register. If the matching tests are passed, the same number of original digits are output (because that indicates a value's size -- byte, word, or long). For a hex string to be modified, the following tests must be passed: • There must have been exactly 2, 4, or 8 digits. Only hex strings $XX, $XXXX, and $XXXXXXXX are possible candidates because that is the only way the Disassembler generates offsets. • Hex string must be delimited by a "(" or a ",". The "(" allows offsets for $XXXX(An,...) and $XX(An,Xn) addressing modes. The comma allows for the MC68020 addressing forms. • The "$X..." must NOT be preceded by a "±". This eliminates the possibility of modifying the offset of a PC-relative addressing mode always generated in the form "*±$XXXX". • The "$X..." must NOT be preceded by a "#". This eliminates modifying immediate data. • Value must be negative. Negative values are the only values we modify. A value $FFFF is modified to -$0001. */ æKY showMacsBugSymbol æFc DisAsmLookup.h æT Function æD char *showMacsBugSymbol(char *symStart,void *limit,char *operand,short *bytesUsed); æDT char myVariable = showMacsBugSymbol((char *)symStart,(void *)limit,(char *)operand, (short *)bytesUsed); æC /* Format a MacsBug symbol as a operand of a DC.B directive. The first one or two bytes of the symbol are generated as $80+'c' if they have there high high bits set. All other characters are shown as characters in a string constant. The pad byte, if present, is one is also shown as $00. This routine is called to check that the bytes pointed to by symStart represent a valid MacsBug symbol. The symbol must be fully contained in the bytes starting at symStart, up to, but not including the byte pointed to by the limit parameter. When called, showMacsBugSymbol assumes that symStart is pointing at a valid MacsBug symbol as validated by the validMacsBugSymbol or endOfModule routines. As with validMacsBugSymbol, the symbol must be fully contained in the bytes starting at symStart up to, but not including, the byte pointed to by the end parameter. The string is returned in the 'operand' parameter as a null terminated Pascal string. The function also returns a pointer to this string as its return value (NULL is returned only if the byte pointed to by the limit parameter is reached prior to processing the entire symbol -- which should not happen if properly validated). The number of bytes used for the symbol is returned in bytesUsed. Due to the way MacsBug symbols are encoded, bytesUsed may not necessarily be the same as the length of the operand string. A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and upper/lower case letters in a format determined by the first two bytes of the symbol as described in the validMacsBugSymbol routine. */ æKY validMacsBugSymbol æFc DisAsmLookup.h æT Function æD char *validMacsBugSymbol(char *symStart,void *limit,char *symbol); æDT char myVariable = validMacsBugSymbol((char *)symStart,(void *)limit, (char *)symbol); æC /* Check that the bytes pointed to by symStart represents a valid MacsBug symbol. The symbol must be fully contained in the bytes starting at symStart, up to, but not including, the byte pointed to by the limit parameter. If a valid symbol is NOT found, then NULL is returned as the function's result. However, if a valid symbol is found, it is copied to symbol (if it is not NULL) as a null terminated Pascal string, and return a pointer to where we think the FOLLOWING module begins. In the "old style" cases (see below) this will always be 8 or 16 bytes after the input symStart. For new style Apple Pascal and C cases this will depend on the symbol length, existence of a pad byte, and size of the constant (literal) area. In all cases, trailing blanks are removed from the symbol. A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and upper/lower case letters in a format determined by the first two bytes of the symbol as follows: 1st byte | 2nd byte | Byte | Range | Range | Length | Comments ============================================================================== $20 - $7F | $20 - $7F | 8 | "Old style" MacsBug symbol format $A0 - $FF | $20 - $7F | 8 | "Old style" MacsBug symbol format ------------------------------------------------------------------------------ $20 - $7F | $80 - $FF | 16 | "Old style" MacApp symbol ab==>b.a $A0 - $FF | $80 - $FF | 16 | "Old style" MacApp symbol ab==>b.a ------------------------------------------------------------------------------ $80 | $01 - $FF | n | n = 2nd byte (Apple Compiler symbol) $81 - $9F | $00 - $FF | m | m = 1st byte & $7F (Apple Compiler symbol) ============================================================================== The formats are determined by whether bit 7 is set in the first and second bytes. This bit will removed when we find it or'ed into the first and/or second valid symbol characters. The first two formats in the above table are the basic "old style" (pre- existing) MacsBug formats. The first byte may or may not have bit 7 set the second byte is a valid symbol character. The first byte (with bit 7 removed) and the next 7 bytes are assumed to comprise the symbol. The second pair of formats are also "old style" formats, but used for MacApp symbols. Bit 7 set in the second character indicates these formats. The symbol is assumed to be 16 bytes with the second 8 bytes preceding the first 8 bytes in the generated symbol. For example, 12345678abcdefgh represents the symbol abcdefgh.12345678. The last pair of formats are reserved by Apple and generated by the MPW Pascal and C compilers. In these cases the value of the first byte is always between $80 and $9F, or with bit 7 removed, between $00 and $1F. For $00, the second byte is the length of the symbol with that many bytes following the second byte (thus a max length of 255). Values $01 to $1F represent the length itself. A pad byte may follow these variable length cases if the symbol does not end on a word boundary. Following the symbol and the possible pad byte is a word containing the size of the constants (literals) generated by the compiler. Note that if symStart actually does point to a valid MacsBug symbol, then you may use showMacsBugSymbol to convert the MacsBug symbol bytes to a string that could be used as a DC.B operand for disassembly purposes. This string explicitly shows the MacsBug symbol encodings. */ æKY DiskInit.h æKL DIBadMount dibadmount DIFormat DILoad DIUnload DIVerify dizero DIZero HFSDefaults æKY HFSDefaults æFc DiskInit.h æT struct æD struct HFSDefaults { char sigWord[2]; /* signature word*/ long abSize; /* allocation block size in bytes*/ long clpSize; /* clump size in bytes*/ long nxFreeFN; /* next free file number*/ long btClpSize; /* B-Tree clump size in bytes*/ short rsrv1; /* reserved*/ short rsrv2; /* reserved*/ short rsrv3; /* reserved*/ }; typedef struct HFSDefaults HFSDefaults; æC »Formatting Hierarchical Volumes The Disk Initialization Package must set certain volume characteristics when placing a hierarchical file directory on a volume. Default values for these volume characteristics are stored in the 128K ROM; this section is for advanced programmers who want to substitute their own values. The record containing the default values, if defined in Pascal, would look like this: TYPE HFSDefaults = PACKED RECORD sigWord: ARRAY[1..2] OF CHAR; {signature word} abSize: LONGINT; {allocation block size in bytes} clpSize: LONGINT; {clump size in bytes} nxFreeFN: LONGINT; {next free file number} btClpSize: LONGINT; {B*-Tree clump size in bytes} rsrv1: INTEGER; {reserved} rsrv2: INTEGER; {reserved} rsrv3: INTEGER; {reserved} END; The default values for these fields are as follows: Field Default value sigWord 'BD' abSize 0 clpSize 4 * abSize nxFreeFN 16 btClpSize 0 To supply your own values for these fields, create a similar, nonrelocatable record containing the desired values and place a pointer to it in the global variable FmtDefaults. To restore the system defaults, simply clear FmtDefaults. The sigWord must equal 'BD' (meaning “big disk”) for the volume to be recognized as a hierarchical volume. If the specified allocation block size is 0, the allocation block size is calculated according to the size of the volume: abSize = (1 + (volSize in blocks / 64K)) * 512 bytes If the specified B*-tree clump size is 0, the clump size for both the catalog and extent trees is calculated according to the size of the volume: btClpSize = (volSize in blocks)/128 * 512bytes æKY DILoad æFc DiskInit.h æT Function æD pascal void DILoad(void); æDT DILoad()(void); æMM æRI II-396 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DILoad reads the Disk Initialization Package, and its associated dialog and dialog items, from the system resource file into memory and makes them unpurgeable. Note: DIFormat, DIVerify, and DIZero don’t need the dialog, so if you use only these routines you can call the Resource Manager function GetResource to read just the package resource into memory (and the Memory Manager procedure HNoPurge to make it unpurgeable). æKY DIUnload æFc DiskInit.h æT Function æD pascal void DIUnload(void); æDT DIUnload()(void); æMM æRI II-396 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIUnload makes the Disk Initialization Package (and its associated dialog and dialog items) purgeable. æKY DIBadMount æFc DiskInit.h æT Function æD pascal short DIBadMount(Point where,long evtMessage); æDT short myVariable = DIBadMount((Point) where,(long) evtMessage); æRI DIBadMount function II-396, N70-1, P-34, 168 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 Call DIBadMount when a disk-inserted event occurs if the result code in the high-order word of the associated event message indicates an error (that is, the result code is other than noErr). Given the event message in evtMessage, DIBadMount evaluates the result code and either ejects the disk or lets the user initialize and name it. The low-order word of the event message contains the drive number. The where parameter specifies the location (in global coordinates) of the top left corner of the dialog box displayed by DIBadMount. If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr, DIBadMount simply ejects the disk from the drive and returns the result code. If the result code ioErr, badMDBErr, or noMacDskErr is passed, the error can be corrected by initializing the disk; DIBadMount displays a dialog box that describes the problem and asks whether the user wants to initialize the disk. For the result code ioErr, the dialog box shown in Figure 1 is displayed. (This happens if the disk is brand new.) For badMDBErr and noMacDskErr, DIBadMount displays a similar dialog box in which the description of the problem is “This disk is damaged” and “This is not a Macintosh disk”, respectively. •••Refer to Figure 1.••• Figure 1–Disk Initialization Dialog for IOErr Note: Before presenting the disk initialization dialog, DIBadMount checks whether the drive contains an already mounted volume; if so, it ejects the disk and returns 2 as its result. This will happen rarely and may reflect an error in your program (for example, you forgot to call DILoad and the user had to switch to the disk containing the system resource file). If the user responds to the disk initialization dialog by clicking the Eject button, DIBadMount ejects the disk and returns 1 as its result. If the Initialize button is clicked, a box displaying the message “Initializing disk...” appears, and DIBadMount attempts to initialize the disk. If initialization fails, the disk is ejected and the user is informed as shown in Figure 2; after the user clicks OK, DIBadMount returns a negative result code ranging from firstDskErr to lastDskErr, indicating that a low-level disk error occurred. •••Refer to Figure 2.••• Figure 2–Initialization Failure Dialog If the disk is successfully initialized, the dialog box in Figure 3 appears. After the user names the disk and clicks OK, DIBadMount mounts the volume by calling the File Manager function MountVol and returns MountVol’s result code (noErr if no error occurs). •••Refer to Figure 3.••• Figure 3–Dialog for Naming a Disk Result codes noErr No error extFSErr External file system memFullErr Not enough room in heap zone nsDrvErr No such drive paramErr Bad drive number volOnLinErr Volume already on-line firstDskErr Low-level disk error through lastDskErr Other results 1 User clicked Eject 2 Mounted volume in drive æKY dibadmount æFc DiskInit.h æT Function æD OSErr dibadmount(Point *where,long evtMessage); æDT OSErr myVariable = dibadmount((Point *) where,(long) evtMessage); æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 Call DIBadMount when a disk-inserted event occurs if the result code in the high-order word of the associated event message indicates an error (that is, the result code is other than noErr). Given the event message in evtMessage, DIBadMount evaluates the result code and either ejects the disk or lets the user initialize and name it. The low-order word of the event message contains the drive number. The where parameter specifies the location (in global coordinates) of the top left corner of the dialog box displayed by DIBadMount. If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr, DIBadMount simply ejects the disk from the drive and returns the result code. If the result code ioErr, badMDBErr, or noMacDskErr is passed, the error can be corrected by initializing the disk; DIBadMount displays a dialog box that describes the problem and asks whether the user wants to initialize the disk. For the result code ioErr, the dialog box shown in Figure 1 is displayed. (This happens if the disk is brand new.) For badMDBErr and noMacDskErr, DIBadMount displays a similar dialog box in which the description of the problem is “This disk is damaged” and “This is not a Macintosh disk”, respectively. •••Refer to Figure 1.••• Figure 1–Disk Initialization Dialog for IOErr Note: Before presenting the disk initialization dialog, DIBadMount checks whether the drive contains an already mounted volume; if so, it ejects the disk and returns 2 as its result. This will happen rarely and may reflect an error in your program (for example, you forgot to call DILoad and the user had to switch to the disk containing the system resource file). If the user responds to the disk initialization dialog by clicking the Eject button, DIBadMount ejects the disk and returns 1 as its result. If the Initialize button is clicked, a box displaying the message “Initializing disk...” appears, and DIBadMount attempts to initialize the disk. If initialization fails, the disk is ejected and the user is informed as shown in Figure 2; after the user clicks OK, DIBadMount returns a negative result code ranging from firstDskErr to lastDskErr, indicating that a low-level disk error occurred. •••Refer to Figure 2.••• Figure 2–Initialization Failure Dialog If the disk is successfully initialized, the dialog box in Figure 3 appears. After the user names the disk and clicks OK, DIBadMount mounts the volume by calling the File Manager function MountVol and returns MountVol’s result code (noErr if no error occurs). •••Refer to Figure 3.••• Figure 3–Dialog for Naming a Disk Result codes noErr No error extFSErr External file system memFullErr Not enough room in heap zone nsDrvErr No such drive paramErr Bad drive number volOnLinErr Volume already on-line firstDskErr Low-level disk error through lastDskErr Other results 1 User clicked Eject 2 Mounted volume in drive æKY DIFormat æFc DiskInit.h æT Function æD pascal OSErr DIFormat(short drvNum); æDT OSErr myVariable = DIFormat((short) drvNum); æMM æRI II-398 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIFormat formats the disk in the drive specified by the given drive number and returns a result code indicating whether the formatting was completed successfully or failed. Formatting a disk consists of writing special information onto it so that the Disk Driver can read from and write to the disk. Result codes noErr No error firstDskErr Low-level disk error through lastDskErr æKY DIVerify æFc DiskInit.h æT Function æD pascal OSErr DIVerify(short drvNum); æDT OSErr myVariable = DIVerify((short) drvNum); æMM æRI II-398 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIVerify verifies the format of the disk in the drive specified by the given drive number; it reads each bit from the disk and returns a result code indicating whether all bits were read successfully or not. DIVerify doesn’t affect the contents of the disk itself. Result codes noErr No error firstDskErr Low-level disk error through lastDskErr æKY DIZero æFc DiskInit.h æT Function æD pascal OSErr DIZero(short drvNum,ConstStr255Param volName); æDT OSErr myVariable = DIZero((short) drvNum,(ConstStr255Param) volName); æMM æRT 70 æRI II-399, N70-2 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 On the unmounted volume in the drive specified by the given drive number, DIZero writes the volume information, a block map, and a file directory as for a volume with no files; the volName parameter specifies the volume name to be included in the volume information. This is the last step in initialization (after formatting and verifying) and makes any files that are already on the volume permanently inaccessible. If the operation fails, DIZero returns a result code indicating that a low-level disk error occurred; otherwise, it mounts the volume by calling the File Manager function MountVol and returns MountVol’s result code (noErr if no error occurs). Result codes noErr No error badMDBErr Bad master directory block extFSErr External file system ioErr I/O error memFullErr Not enough room in heap zone noMacDskErr Not a Macintosh disk nsDrvErr No such drive paramErr Bad drive number volOnLinErr Volume already on-line firstDskErr Low-level disk error through lastDskErr æKY dizero æFc DiskInit.h æT Function æD OSErr dizero(short drvnum,char *volName); æDT OSErr myVariable = dizero((short) drvnum,(char *) volName); æC æKY Disks.h æKL DiskEject DriveStatus SetTagBuffer DrvSts DrvSts2 æKY DrvSts æFc Disks.h æT struct æD struct DrvSts { short track; char writeProt; char diskInPlace; char installed; char sides; QElemPtr qLink; short qType; short dQDrive; short dQRefNum; short dQFSID; char twoSideFmt; char needsFlush; short diskErrs; }; typedef struct DrvSts DrvSts; æC æKY DrvSts2 æFc Disks.h æT struct æD struct DrvSts2 { short track; char writeProt; char diskInPlace; char installed; char sides; QElemPtr qLink; short qType; short dQDrive; short dQRefNum; short dQFSID; short driveSize; short driveS1; short driveType; short driveManf; short driveChar; char driveMisc; }; typedef struct DrvSts2 DrvSts2; æC æKY DiskEject æFc Disks.h æT Function æD pascal OSErr DiskEject(short drvNum); æDT OSErr myVariable = DiskEject((short) drvNum); æMM æRI II-214 æC [Not in ROM] Assembly-language note: DiskEject is equivalent to a Control call with csCode equal to the global constant ejectCode. DiskEject ejects the disk from the internal drive if drvNum is 1, or from the external drive if drvNum is 2. Result codes noErr No error nsDrvErr No such drive æKY SetTagBuffer æFc Disks.h æT Function æD pascal OSErr SetTagBuffer(void *buffPtr); æDT OSErr myVariable = SetTagBuffer((void *) buffPtr); æMM æRI II-214 æC [Not in ROM] Assembly-language note: SetTagBuffer is equivalent to a Control call with csCode equal to the global constant tgBuffCode. An application can change the information used in the file tags buffer by calling SetTagBuffer. The buffPtr parameter points to a buffer that contains the information to be used. If buffPtr is NIL, the information in the file tags buffer isn’t changed. If buffPtr isn’t NIL, every time the Disk Driver reads a sector from the disk, it stores the file tags in the file tags buffer and in the buffer pointed to by buffPtr. Every time the Disk Driver writes a sector onto the disk, it reads 12 bytes from the buffer pointed to by buffPtr, places them in the file tags buffer, and then writes them onto the disk. The contents of the buffer pointed to by buffPtr are overwritten at the end of every read request (which can be composed of a number of sectors) instead of at the end of every sector. Each read request places 12 bytes in the buffer for each sector, always beginning at the start of the buffer. This way an application can examine the file tags for a number of sequentially read sectors. If a read request is composed of a number of sectors, the Disk Driver places 12 bytes in the buffer for each sector. For example, for a read request of five sectors, the Disk Driver will place 60 bytes in the buffer. Result codes noErr No error æKY DriveStatus æFc Disks.h æT Function æD pascal OSErr DriveStatus(short drvNum,DrvSts *status); æDT OSErr myVariable = DriveStatus((short) drvNum,(DrvSts *) status); æMM æRI II-215 æC [Not in ROM] Assembly-language note: DriveStatus is equivalent to a Status call with csCode equal to the global constant drvStsCode; status is returned in csParam through csParam+21. DriveStatus returns information about the internal drive if drvNum is 1, or about the external drive if drvNum is 2. The information is returned in a record of type DrvSts: TYPE DrvSts = RECORD track: INTEGER; {current track} writeProt: SignedByte; {bit 7=1 if volume is locked} diskInPlace: SignedByte; {disk in place} installed: SignedByte; {drive installed} sides: SignedByte; {bit 7=0 if single-side drive} qLink: QElemPtr; {next queue entry} qType: INTEGER; {reserved for future use} dQDrive: INTEGER; {drive number} dQRefNum: INTEGER; {driver reference number} dQFSID: INTEGER; {file-system identifier} twoSideFmt: SignedByte; {-1 if two-sided disk} needsFlush: SignedByte; {reserved for future use} diskErrs: INTEGER {error count} END; The diskInPlace field is 0 if there’s no disk in the drive, 1 or 2 if there is a disk in the drive, or –4 to –1 if the disk was ejected in the last 1.5 seconds. The installed field is 1 if the drive is connected to the Macintosh, 0 if the drive might be connected to the Macintosh, and –1 if the drive isn’t installed. The value of twoSideFmt is valid only when diskInPlace=2. The value of diskErrs is incremented every time an error occurs internally within the Disk Driver. Result codes noErr No error nsDrvErr No such drive æKY Editions.h æKL AssociateSection CallEditionOpenerProc CallFormatIOProc CloseEdition CreateEditionContainerFile DeleteEditionContainerFile EditionHasFormat GetEditionFormatMark GetEditionInfo GetEditionOpenerProc GetLastEditionContainerUsed GetStandardFormats GoToPublisherSection InitEditionPack IsRegisteredSection NewPublisherDialog NewPublisherExpDialog NewSection NewSubscriberDialog NewSubscriberExpDialog OpenEdition OpenNewEdition ReadEdition RegisterSection SectionOptionsDialog SectionOptionsExpDialog SetEditionFormatMark SetEditionOpenerProc UnRegisterSection WriteEdition EditionContainerSpec EditionContainerSpecPtr EditionInfoRecord EditionOpenerParamBlock EditionOpenerProcPtr EditionOpenerVerb EditionRefNum emCancelSectionDialogRefCon emGoToPubErrDialogRefCon emHookAutoUpdateMode emHookCancelSection emHookGetEditionNow emHookGoToPublisher emHookManualUpdateMode emHookRedrawPreview emHookSendEditionNow emOptionsDialogRefCon eoCanSubscribe eoClose eoCloseNew eoOpen eoOpenNew ExpDlgHookProcPtr ExpModalFilterProcPtr FormatIOParamBlock FormatIOProcPtr FormatIOVerb FormatType ioHasFormat ioNewFormat ioReadFormat ioWriteFormat kFormatLengthUnknown kFormatListFormat kPartNumberUnknown kPartsNotUsed kPICTEditionFileType kPICTformatMask kPreviewFormat kPreviewHeight kPreviewWidth kPublisherDocAliasFormat ksndEditionFileType ksndFormatMask kTEXTEditionFileType kTEXTformatMask kUnknownEditionFileType NewPublisherReply NewSubscriberReply pumManual pumOnSave rSectionType sectionCancelMsgID sectionEventMsgClass SectionHandle SectionOptionsReply SectionPtr sectionReadMsgID SectionRecord sectionScrollMsgID SectionType sectionWriteMsgID stPublisher stSubscriber sumAutomatic sumManual TimeStamp UpdateMode æKY rSectionType æFc Editions.h æT #define æD #define rSectionType 'sect' /* ResType of saved SectionRecords */ æC æKY stSubscriber æFc Editions.h æT æD stSubscriber = 0x01, æC æKY stPublisher æFc Editions.h æT æD stPublisher = 0x0A, æC æKY sumAutomatic æFc Editions.h æT æD sumAutomatic = 0, /* subscriber update mode - Automatically */ æC æKY sumManual æFc Editions.h æT æD sumManual = 1, /* subscriber update mode - Manually */ æC æKY pumOnSave æFc Editions.h æT æD pumOnSave = 0, /* publisher update mode - OnSave */ æC æKY pumManual æFc Editions.h æT æD pumManual = 1, /* publisher update mode - Manually */ æC æKY kPartsNotUsed æFc Editions.h æT æD kPartsNotUsed = 0, æC æKY kPartNumberUnknown æFc Editions.h æT æD kPartNumberUnknown = -1, /* misc */ æC æKY kPreviewWidth æFc Editions.h æT æD kPreviewWidth = 120, æC æKY kPreviewHeight æFc Editions.h æT æD kPreviewHeight = 120, æC æKY kPublisherDocAliasFormat æFc Editions.h æT #define æD #define kPublisherDocAliasFormat 'alis' æC æKY kPreviewFormat æFc Editions.h æT #define æD #define kPreviewFormat 'prvw' æC æKY kFormatListFormat æFc Editions.h æT #define æD #define kFormatListFormat 'fmts' æC æKY kPICTformatMask æFc Editions.h æT æD kPICTformatMask = 1, æC æKY kTEXTformatMask æFc Editions.h æT æD kTEXTformatMask = 2, æC æKY ksndFormatMask æFc Editions.h æT æD ksndFormatMask = 4, æC æKY kPICTEditionFileType æFc Editions.h æT #define æD #define kPICTEditionFileType 'edtp' æC æKY kTEXTEditionFileType æFc Editions.h æT #define æD #define kTEXTEditionFileType 'edtt' æC æKY ksndEditionFileType æFc Editions.h æT #define æD #define ksndEditionFileType 'edts' æC æKY kUnknownEditionFileType æFc Editions.h æT #define æD #define kUnknownEditionFileType 'edtu' æC æKY emHookRedrawPreview æFc Editions.h æT æD emHookRedrawPreview = 150, æC æKY emHookCancelSection æFc Editions.h æT æD emHookCancelSection = 160, æC æKY emHookGoToPublisher æFc Editions.h æT æD emHookGoToPublisher = 161, æC æKY emHookGetEditionNow æFc Editions.h æT æD emHookGetEditionNow = 162, æC æKY emHookSendEditionNow æFc Editions.h æT æD emHookSendEditionNow = 162, æC æKY emHookManualUpdateMode æFc Editions.h æT æD emHookManualUpdateMode = 163, æC æKY emHookAutoUpdateMode æFc Editions.h æT æD emHookAutoUpdateMode = 164, æC æKY emOptionsDialogRefCon æFc Editions.h æT #define æD #define emOptionsDialogRefCon 'optn' æC æKY emCancelSectionDialogRefCon æFc Editions.h æT #define æD #define emCancelSectionDialogRefCon 'cncl' æC æKY emGoToPubErrDialogRefCon æFc Editions.h æT #define æD #define emGoToPubErrDialogRefCon 'gerr' æC æKY kFormatLengthUnknown æFc Editions.h æT æD kFormatLengthUnknown = -1, æC æKY SectionType æFc Editions.h æT typedef æD typedef char SectionType; /* one byte, stSubscriber or stPublisher */ æC æKY TimeStamp æFc Editions.h æT typedef æD typedef unsigned long TimeStamp; /* seconds since 1904 */ æC æKY FormatType æFc Editions.h æT typedef æD typedef unsigned long FormatType;/* similar to ResType */ æC æKY EditionRefNum æFc Editions.h æT typedef æD typedef Handle EditionRefNum; /* used in Edition I/O */ æC æKY UpdateMode æFc Editions.h æT typedef æD typedef short UpdateMode; /* sumAutomatic, pumSuspend, etc */ æC æKY SectionRecord SectionPtr SectionHandle æFc Editions.h æT struct æD struct SectionRecord { SignedByte version; /* always 0x01 in system 7.0 */ SectionType kind; /* stSubscriber or stPublisher */ UpdateMode mode; /* auto or manual */ TimeStamp mdDate; /* last change in document */ long sectionID; /* app. specific, unique per document */ long refCon; /* application specific */ AliasHandle alias; /* handle to Alias Record */ long subPart; /* which part of container file */ struct SectionRecord **nextSection; /* for linked list of app's Sections */ Handle controlBlock; /* used internally */ EditionRefNum refNum; /* used internally */ }; typedef struct SectionRecord SectionRecord; typedef SectionRecord *SectionPtr, **SectionHandle; æC æKY EditionContainerSpec EditionContainerSpecPtr æFc Editions.h æT struct æD struct EditionContainerSpec { FSSpec theFile; ScriptCode theFileScript; long thePart; Str31 thePartName; ScriptCode thePartScript; }; typedef struct EditionContainerSpec EditionContainerSpec; typedef EditionContainerSpec *EditionContainerSpecPtr; æC æKY EditionInfoRecord æFc Editions.h æT struct æD struct EditionInfoRecord { TimeStamp crDate; /* date EditionContainer was created */ TimeStamp mdDate; /* date of last change */ OSType fdCreator; /* file creator */ OSType fdType; /* file type */ EditionContainerSpec container; /* the Edition */ }; typedef struct EditionInfoRecord EditionInfoRecord; æC æKY NewPublisherReply æFc Editions.h æT struct æD struct NewPublisherReply { Boolean canceled; /* O */ Boolean replacing ; Boolean usePart; /* I */ Handle preview; /* I */ FormatType previewFormat; /* I */ EditionContainerSpec container; /* I/O */ }; typedef struct NewPublisherReply NewPublisherReply; æC æKY NewSubscriberReply æFc Editions.h æT struct æD struct NewSubscriberReply { Boolean canceled; /* O */ unsigned char formatsMask; EditionContainerSpec container; /*I/O*/ }; typedef struct NewSubscriberReply NewSubscriberReply; æC æKY SectionOptionsReply æFc Editions.h æT struct æD struct SectionOptionsReply { Boolean canceled; /* O */ Boolean changed; /* O */ SectionHandle sectionH; /* I */ ResType action; /* O */ }; typedef struct SectionOptionsReply SectionOptionsReply; æC æKY ExpModalFilterProcPtr æFc Editions.h æT typedef æD typedef pascal Boolean (*ExpModalFilterProcPtr) (DialogPtr theDialog, EventRecord *theEvent, short itemOffset, short *itemHit, Ptr yourDataPtr); æC æKY ExpDlgHookProcPtr æFc Editions.h æT typedef æD typedef pascal short (*ExpDlgHookProcPtr) (short itemOffset, short itemHit, DialogPtr theDialog, Ptr yourDataPtr); æC æKY FormatIOVerb ioHasFormat ioReadFormat ioNewFormat ioWriteFormat æFc Editions.h æT enum æD enum {ioHasFormat,ioReadFormat,ioNewFormat,ioWriteFormat}; typedef unsigned char FormatIOVerb; æC æKY FormatIOParamBlock æFc Editions.h æT struct æD struct FormatIOParamBlock { long ioRefNum; FormatType format; long formatIndex; unsigned long offset; Ptr buffPtr; unsigned long buffLen; }; typedef struct FormatIOParamBlock FormatIOParamBlock; æC æKY FormatIOProcPtr æFc Editions.h æT typedef æD typedef pascal short (*FormatIOProcPtr) (FormatIOVerb selector, FormatIOParamBlock *PB); æC æKY EditionOpenerVerb eoOpen eoClose eoOpenNew eoCloseNew eoCanSubscribe æFc Editions.h æT enum æD enum {eoOpen,eoClose,eoOpenNew,eoCloseNew,eoCanSubscribe}; typedef unsigned char EditionOpenerVerb; æC æKY EditionOpenerParamBlock æFc Editions.h æT struct æD struct EditionOpenerParamBlock { EditionInfoRecord info; SectionHandle sectionH; FSSpecPtr document; OSType fdCreator; long ioRefNum; FormatIOProcPtr ioProc; Boolean success; unsigned char formatsMask; }; typedef struct EditionOpenerParamBlock EditionOpenerParamBlock; æC æKY EditionOpenerProcPtr æFc Editions.h æT typedef æD typedef pascal short (*EditionOpenerProcPtr) (EditionOpenerVerb selector, FormatIOParamBlock *PB); æC æKY sectionEventMsgClass æFc Editions.h æT #define æD #define sectionEventMsgClass 'sect' æC æKY sectionReadMsgID æFc Editions.h æT #define æD #define sectionReadMsgID 'read' æC æKY sectionWriteMsgID æFc Editions.h æT #define æD #define sectionWriteMsgID 'writ' æC æKY sectionScrollMsgID æFc Editions.h æT #define æD #define sectionScrollMsgID 'scrl' æC æKY sectionCancelMsgID æFc Editions.h æT #define æD #define sectionCancelMsgID 'cncl' æC æKY InitEditionPack æFc Editions.h æT Function æTN A82D æD pascal OSErr InitEditionPack(void) = {0x3F3C,0x0011,0x303C,0x0100,0xA82D}; æDT OSErr myVariable = InitEditionPack()(void); æC æKY NewSection æFc Editions.h æT Function æTN A82D æD pascal OSErr NewSection(const EditionContainerSpec *container, const FSSpec *sectionDocument, SectionType kind, long sectionID, UpdateMode initalMode, SectionHandle *sectionH) = {0x303C,0x0A02,0xA82D}; æDT OSErr myVariable = NewSection((const EditionContainerSpec *) container,( const FSSpec) * sectionDocument,() SectionType kind,() long sectionID,() UpdateMode initalMode,( SectionHandle) * sectionH); æC æKY RegisterSection æFc Editions.h æT Function æTN A82D æD pascal OSErr RegisterSection(const FSSpec *sectionDocument, SectionHandle sectionH, Boolean *aliasWasUpdated) = {0x303C,0x0604,0xA82D}; æDT OSErr myVariable = RegisterSection((const FSSpec *) sectionDocument,() SectionHandle sectionH,( Boolean) * aliasWasUpdated); æC æKY UnRegisterSection æFc Editions.h æT Function æTN A82D æD pascal OSErr UnRegisterSection(SectionHandle sectionH) = {0x303C,0x0206,0xA82D}; æDT OSErr myVariable = UnRegisterSection((SectionHandle) sectionH); æC æKY IsRegisteredSection æFc Editions.h æT Function æTN A82D æD pascal OSErr IsRegisteredSection(SectionHandle sectionH) = {0x303C,0x0208,0xA82D}; æDT OSErr myVariable = IsRegisteredSection((SectionHandle) sectionH); æC æKY AssociateSection æFc Editions.h æT Function æTN A82D æD pascal OSErr AssociateSection(SectionHandle sectionH, const FSSpec *newSectionDocument) = {0x303C,0x040C,0xA82D}; æDT OSErr myVariable = AssociateSection((SectionHandle) sectionH,( const FSSpec) * newSectionDocument); æC æKY CreateEditionContainerFile æFc Editions.h æT Function æTN A82D æD pascal OSErr CreateEditionContainerFile(const FSSpec *editionFile, OSType fdCreator, ScriptCode editionFileNameScript) = {0x303C,0x050E,0xA82D}; æDT OSErr myVariable = CreateEditionContainerFile((const FSSpec *) editionFile,() OSType fdCreator,() ScriptCode editionFileNameScript); æC æKY DeleteEditionContainerFile æFc Editions.h æT Function æTN A82D æD pascal OSErr DeleteEditionContainerFile(const FSSpec *editionFile) = {0x303C,0x0210,0xA82D}; æDT OSErr myVariable = DeleteEditionContainerFile((const FSSpec *) editionFile); æC æKY OpenEdition æFc Editions.h æT Function æTN A82D æD pascal OSErr OpenEdition(SectionHandle subscriberSectionH, EditionRefNum *refNum) = {0x303C,0x0412,0xA82D}; æDT OSErr myVariable = OpenEdition((SectionHandle) subscriberSectionH,( EditionRefNum) * refNum); æC æKY OpenNewEdition æFc Editions.h æT Function æTN A82D æD pascal OSErr OpenNewEdition(SectionHandle publisherSectionH, OSType fdCreator, const FSSpec *publisherSectionDocument, EditionRefNum *refNum) = {0x303C,0x0814,0xA82D}; æDT OSErr myVariable = OpenNewEdition((SectionHandle) publisherSectionH,() OSType fdCreator,( const FSSpec) * publisherSectionDocument,( EditionRefNum) * refNum); æC æKY CloseEdition æFc Editions.h æT Function æTN A82D æD pascal OSErr CloseEdition(EditionRefNum whichEdition, Boolean successful) = {0x303C,0x0316,0xA82D}; æDT OSErr myVariable = CloseEdition((EditionRefNum) whichEdition,() Boolean successful); æC æKY EditionHasFormat æFc Editions.h æT Function æTN A82D æD pascal OSErr EditionHasFormat(EditionRefNum whichEdition, FormatType whichFormat, Size *formatSize) = {0x303C,0x0618,0xA82D}; æDT OSErr myVariable = EditionHasFormat((EditionRefNum) whichEdition,() FormatType whichFormat,( Size) * formatSize); æC æKY ReadEdition æFc Editions.h æT Function æTN A82D æD pascal OSErr ReadEdition(EditionRefNum whichEdition, FormatType whichFormat, void *buffPtr, Size *buffLen) = {0x303C,0x081A,0xA82D}; æDT OSErr myVariable = ReadEdition((EditionRefNum) whichEdition,() FormatType whichFormat,( void) * buffPtr,( Size) * buffLen); æC æKY WriteEdition æFc Editions.h æT Function æTN A82D æD pascal OSErr WriteEdition(EditionRefNum whichEdition, FormatType whichFormat, const void *buffPtr, Size buffLen) = {0x303C,0x081C,0xA82D}; æDT OSErr myVariable = WriteEdition((EditionRefNum) whichEdition,() FormatType whichFormat,( const void) * buffPtr,() Size buffLen); æC æKY GetEditionFormatMark æFc Editions.h æT Function æTN A82D æD pascal OSErr GetEditionFormatMark(EditionRefNum whichEdition, FormatType whichFormat, unsigned long *currentMark) = {0x303C,0x061E,0xA82D}; æDT OSErr myVariable = GetEditionFormatMark((EditionRefNum) whichEdition,() FormatType whichFormat,( unsigned long) * currentMark); æC æKY SetEditionFormatMark æFc Editions.h æT Function æTN A82D æD pascal OSErr SetEditionFormatMark(EditionRefNum whichEdition, FormatType whichFormat, unsigned long setMarkTo) = {0x303C,0x0620,0xA82D}; æDT OSErr myVariable = SetEditionFormatMark((EditionRefNum) whichEdition,() FormatType whichFormat,( unsigned) long setMarkTo); æC æKY GetEditionInfo æFc Editions.h æT Function æTN A82D æD pascal OSErr GetEditionInfo(const SectionHandle sectionH, EditionInfoRecord *editionInfo) = {0x303C,0x0422,0xA82D}; æDT OSErr myVariable = GetEditionInfo((const SectionHandle) sectionH,( EditionInfoRecord) * editionInfo); æC æKY GoToPublisherSection æFc Editions.h æT Function æTN A82D æD pascal OSErr GoToPublisherSection(const EditionContainerSpec *container) = {0x303C,0x0224,0xA82D}; æDT OSErr myVariable = GoToPublisherSection((const EditionContainerSpec *) container); æC æKY GetLastEditionContainerUsed æFc Editions.h æT Function æTN A82D æD pascal OSErr GetLastEditionContainerUsed(EditionContainerSpec *container) = {0x303C,0x0226,0xA82D}; æDT OSErr myVariable = GetLastEditionContainerUsed((EditionContainerSpec *) container); æC æKY GetStandardFormats æFc Editions.h æT Function æTN A82D æD pascal OSErr GetStandardFormats(const EditionContainerSpec *container, FormatType *previewFormat, Handle preview, Handle publisherAlias, Handle formats) = {0x303C,0x0A28,0xA82D}; æDT OSErr myVariable = GetStandardFormats((const EditionContainerSpec *) container,( FormatType) * previewFormat,() Handle preview,() Handle publisherAlias,() Handle formats); æC æKY GetEditionOpenerProc æFc Editions.h æT Function æTN A82D æD pascal OSErr GetEditionOpenerProc(EditionOpenerProcPtr *opener) = {0x303C,0x022A,0xA82D}; æDT OSErr myVariable = GetEditionOpenerProc((EditionOpenerProcPtr *) opener); æC æKY SetEditionOpenerProc æFc Editions.h æT Function æTN A82D æD pascal OSErr SetEditionOpenerProc(EditionOpenerProcPtr opener) = {0x303C,0x022C,0xA82D}; æDT OSErr myVariable = SetEditionOpenerProc((EditionOpenerProcPtr) opener); æC æKY CallEditionOpenerProc æFc Editions.h æT Function æTN A82D æD pascal OSErr CallEditionOpenerProc(EditionOpenerVerb selector, EditionOpenerParamBlock *PB, EditionOpenerProcPtr routine) = {0x303C,0x052E,0xA82D}; æDT OSErr myVariable = CallEditionOpenerProc((EditionOpenerVerb) selector,( EditionOpenerParamBlock) * PB,() EditionOpenerProcPtr routine); æC æKY CallFormatIOProc æFc Editions.h æT Function æTN A82D æD pascal OSErr CallFormatIOProc(FormatIOVerb selector, FormatIOParamBlock *PB, FormatIOProcPtr routine) = {0x303C,0x0530,0xA82D}; æDT OSErr myVariable = CallFormatIOProc((FormatIOVerb) selector,( FormatIOParamBlock) * PB,() FormatIOProcPtr routine); æC æKY NewSubscriberDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr NewSubscriberDialog(NewSubscriberReply *reply) = {0x303C,0x0232,0xA82D}; æDT OSErr myVariable = NewSubscriberDialog((NewSubscriberReply *) reply); æC æKY NewSubscriberExpDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr NewSubscriberExpDialog(NewSubscriberReply *reply, Point where, short expansionDITLresID, ExpDlgHookProcPtr dlgHook, ExpModalFilterProcPtr filterProc, void *yourDataPtr) = {0x303C,0x0B34,0xA82D}; æDT OSErr myVariable = NewSubscriberExpDialog((NewSubscriberReply *) reply,() Point where,() short expansionDITLresID,() ExpDlgHookProcPtr dlgHook,() ExpModalFilterProcPtr filterProc,( void) * yourDataPtr); æC æKY NewPublisherDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr NewPublisherDialog(NewPublisherReply *reply) = {0x303C,0x0236,0xA82D}; æDT OSErr myVariable = NewPublisherDialog((NewPublisherReply *) reply); æC æKY NewPublisherExpDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr NewPublisherExpDialog(NewPublisherReply *reply, Point where, short expansionDITLresID, ExpDlgHookProcPtr dlgHook, ExpModalFilterProcPtr filterProc, void *yourDataPtr) = {0x303C,0x0B38,0xA82D}; æDT OSErr myVariable = NewPublisherExpDialog((NewPublisherReply *) reply,() Point where,() short expansionDITLresID,() ExpDlgHookProcPtr dlgHook,() ExpModalFilterProcPtr filterProc,( void) * yourDataPtr); æC æKY SectionOptionsDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr SectionOptionsDialog(SectionOptionsReply *reply) = {0x303C,0x023A,0xA82D}; æDT OSErr myVariable = SectionOptionsDialog((SectionOptionsReply *) reply); æC æKY SectionOptionsExpDialog æFc Editions.h æT Function æTN A82D æD pascal OSErr SectionOptionsExpDialog(SectionOptionsReply *reply, Point where, short expansionDITLresID, ExpDlgHookProcPtr dlgHook, ExpModalFilterProcPtr filterProc, void *yourDataPtr) = {0x303C,0x0B3C,0xA82D}; æDT OSErr myVariable = SectionOptionsExpDialog((SectionOptionsReply *) reply,() Point where,() short expansionDITLresID,() ExpDlgHookProcPtr dlgHook,() ExpModalFilterProcPtr filterProc,( void) * yourDataPtr); æC æKY EPPC.h æKL AcceptHighLevelEvent GetPortNameFromProcessSerialNumber GetProcessSerialNumberFromPortName GetSpecificHighLevelEvent PostHighLevelEvent bufferIsSmall connectionInvalid GetSpecificFilterProcPtr HighLevelEventMsg HighLevelEventMsgClass HighLevelEventMsgHdl HighLevelEventMsgPtr kHighLevelEvent msgWasFullyAccepted msgWasNotAccepted msgWasPartiallyAccepted nAttnMsg noOutstandingHLE noUserInteractionAllowed nReturnReceipt priorityMask receiverIDisPSN receiverIDisSessionID receiverIDisSignature receiverIDisTargetID receiverIDMask rtrnReceiptMsgID SenderID SenderIDPtr systemOptionsMask TargetID TargetIDHdl TargetIDPtr æKY kHighLevelEvent æFc EPPC.h æT æD kHighLevelEvent = 23, æC æKY receiverIDMask æFc EPPC.h æT æD receiverIDMask = 0x0000F000, æC æKY receiverIDisPSN æFc EPPC.h æT æD receiverIDisPSN = 0x00008000, æC æKY receiverIDisSignature æFc EPPC.h æT æD receiverIDisSignature = 0x00007000, æC æKY receiverIDisSessionID æFc EPPC.h æT æD receiverIDisSessionID = 0x00006000, æC æKY receiverIDisTargetID æFc EPPC.h æT æD receiverIDisTargetID = 0x00005000, æC æKY systemOptionsMask æFc EPPC.h æT æD systemOptionsMask = 0x00000F00, æC æKY nReturnReceipt æFc EPPC.h æT æD nReturnReceipt = 0x00000200, æC æKY priorityMask æFc EPPC.h æT æD priorityMask = 0x000000FF, æC æKY nAttnMsg æFc EPPC.h æT æD nAttnMsg = 0x00000001, æC æKY bufferIsSmall æFc EPPC.h æT æD bufferIsSmall = -607, æC æKY noOutstandingHLE æFc EPPC.h æT æD noOutstandingHLE = -608, æC æKY connectionInvalid æFc EPPC.h æT æD connectionInvalid = -609, æC æKY noUserInteractionAllowed æFc EPPC.h æT æD noUserInteractionAllowed = -610, /* no user interaction allowed */ æC æKY HighLevelEventMsgClass æFc EPPC.h æT #define æD #define HighLevelEventMsgClass 'jaym' æC æKY rtrnReceiptMsgID æFc EPPC.h æT #define æD #define rtrnReceiptMsgID 'rtrn' æC æKY msgWasPartiallyAccepted æFc EPPC.h æT æD msgWasPartiallyAccepted = 2, æC æKY msgWasFullyAccepted æFc EPPC.h æT æD msgWasFullyAccepted = 1, æC æKY msgWasNotAccepted æFc EPPC.h æT æD msgWasNotAccepted = 0, æC æKY TargetID TargetIDPtr TargetIDHdl æFc EPPC.h æT struct æD struct TargetID { long sessionID; PPCPortRec name; LocationNameRec location; PPCPortRec recvrName; }; typedef struct TargetID TargetID; typedef TargetID *TargetIDPtr, **TargetIDHdl; æC æKY SenderID æFc EPPC.h æT typedef æD typedef TargetID SenderID; æC æKY SenderIDPtr æFc EPPC.h æT typedef æD typedef SenderID *SenderIDPtr; æC æKY HighLevelEventMsg HighLevelEventMsgPtr HighLevelEventMsgHdl æFc EPPC.h æT struct æD struct HighLevelEventMsg { unsigned short HighLevelEventMsgHeaderLength; unsigned short version; unsigned long reserved1; EventRecord theMsgEvent; unsigned long userRefcon; unsigned long postingOptions; unsigned long msgLength; }; typedef struct HighLevelEventMsg HighLevelEventMsg; typedef HighLevelEventMsg *HighLevelEventMsgPtr, **HighLevelEventMsgHdl; æC æKY PostHighLevelEvent æFc EPPC.h æT Function æTN A88F æD pascal OSErr PostHighLevelEvent(const EventRecord *theEvent, unsigned long receiverID, unsigned long msgRefcon, Ptr msgBuff, unsigned long msgLen, unsigned long postingOptions) = {0x3F3C,0x0034,0xA88F}; æDT OSErr myVariable = PostHighLevelEvent((const EventRecord *) theEvent,( unsigned) long receiverID,( unsigned) long msgRefcon,() Ptr msgBuff,( unsigned) long msgLen,( unsigned) long postingOptions); æC æKY AcceptHighLevelEvent æFc EPPC.h æT Function æTN A88F æD pascal OSErr AcceptHighLevelEvent(TargetID *sender, unsigned long *msgRefcon, Ptr msgBuff, unsigned long *msgLen) = {0x3F3C,0x0033,0xA88F}; æDT OSErr myVariable = AcceptHighLevelEvent((TargetID *) sender,( unsigned long) * msgRefcon,() Ptr msgBuff,( unsigned long) * msgLen); æC æKY GetProcessSerialNumberFromPortName æFc EPPC.h æT Function æTN A88F æD pascal OSErr GetProcessSerialNumberFromPortName(const PPCPortPtr portName, ProcessSerialNumberPtr pPSN) = {0x3F3C,0x0035,0xA88F}; æDT OSErr myVariable = GetProcessSerialNumberFromPortName((const PPCPortPtr) portName,() ProcessSerialNumberPtr pPSN); æC æKY GetPortNameFromProcessSerialNumber æFc EPPC.h æT Function æTN A88F æD pascal OSErr GetPortNameFromProcessSerialNumber(PPCPortPtr portName,const ProcessSerialNumberPtr pPSN) = {0x3F3C,0x0046,0xA88F}; æDT OSErr myVariable = GetPortNameFromProcessSerialNumber((PPCPortPtr) portName,(const ProcessSerialNumberPtr) pPSN); æC æKY GetSpecificFilterProcPtr æFc EPPC.h æT typedef æD typedef pascal Boolean (*GetSpecificFilterProcPtr) (void *yourDataPtr, HighLevelEventMsgPtr msgBuff, const TargetID *sender); æC æKY GetSpecificHighLevelEvent æFc EPPC.h æT Function æTN A88F æD pascal Boolean GetSpecificHighLevelEvent(GetSpecificFilterProcPtr aFilter, void *yourDataPtr,OSErr *err) = {0x3F3C,0x0045,0xA88F}; æDT Boolean myVariable = GetSpecificHighLevelEvent((GetSpecificFilterProcPtr) aFilter,( void) * yourDataPtr,(OSErr *) err); æC æKY ErrMgr.h æKL AddErrInsert addInserts CloseErrMgr GetSysErrText GetToolErrText InitErrMgr æKY AddErrInsert æFc ErrMgr.h æT Function æD void AddErrInsert(unsigned char *insert,unsigned char *msgString); æDT AddErrInsert((unsigned char *)insert,(unsigned char *)msgString); æC /* Add another insert to an error message string.This call is used when more than one insert is to be added to a message (because it contains more than one '^' character). */ æKY addInserts æFc ErrMgr.h æT Function æD unsigned char *addInserts(unsigned char *msgString,unsigned char *insert, ...); æDT unsigned char myVariable = addInserts((unsigned char *)msgString,(unsigned char *)insert, (...)); æC /* Add a set of inserts to an error message string. AddErrInsert is called for each insert parameter specified. */ æKY CloseErrMgr æFc ErrMgr.h æT Function æD void CloseErrMgr(void); æDT CloseErrMgr(); æC /* Ideally a CloseErrMgr should be done at the end of execution to make sure all files opened by the ErrMgr are closed. You can let normal program termination do the closing. But if you are a purist... */ æKY GetSysErrText æFc ErrMgr.h æT Function æD char *GetSysErrText(short msgNbr,char *errMsg); æDT char myVariable = GetSysErrText((short)msgNbr,(char *)errMsg); æC /* Get the error message text corresponding to system error number errNbr from the system error message file (whose name was specified in the InitErrMgr call). The text of the message is returned in errMsg and the function returns a pointer to errMsg. The maximum length of the message is limited to 254 characters. Note, if a system message filename was not specified to InitErrMgr, then the ErrMgr assumes the message file contained in the file "SysErrs.Err". This file is first accessed as "{ShellDirectory}SysErrs.Err" on the assumption that SysErrs.Err is kept in the same directory as the MPW Shell. If the file cannot be opened, then an open is attempted on "SysErrs.Err" in the System Folder. */ æKY GetToolErrText æFc ErrMgr.h æT Function æD char *GetToolErrText(short msgNbr,char *errInsert,char *errMsg); æDT char myVariable = GetToolErrText((short)msgNbr,(char *)errInsert,(char *)errMsg); æC /* Get the error message text corresponding to tool error number errNbr from the tool error message file (whose name was specified in the InitErrMgr call). The text of the message is returned in errMsg and the function returns a pointer to errMsg. The maximum length of the message is limited to 254 characters. If the message is to have an insert, then ErrInsert should be a pointer to it. Otherwise it should be either be a null string or a NULL pointer. Inserts are indicated in error messages by specifying a '^' to indicate where the insert is to be placed. Note, if a tool message filename was not specified to InitErrMgr, then the ErrMgr assumes the message file contained in the data fork of the tool calling the ErrMgr. This name is contained in the Shell variable {Command} and the value of that variable is used to open the error message file. */ æKY InitErrMgr æFc ErrMgr.h æT Function æD void InitErrMgr(char *toolErrFilename,char *sysErrFilename,Boolean showToolErrNbrs); æDT InitErrMgr((char *)toolErrFilename,(char *)sysErrFilename, (Boolean)showToolErrNbrs); æC /* ErrMgr initialization.This must be done before using any other ErrMgr routine. Set showToolErrNbrs to true if you want all tool messages to contain the error number following the message text enclosed in parentheses (e.g., "<msg txt> ([OS] Error <n>)"; system error messages always contain the error number). The toolErrFileName parameter is used to specify the name of a tool-specific error file, and should be the NULL or a null string if not used (or if the tool's data fork is to be used as the error file, see GetToolErrText for futher details). The sysErrFileName parameter is used to specify the name of a system error file, and should normally be the NULL or a null string, which causes the ErrMgr to look in the MPW Shell directory for "SysErrs.Err" (see GetSysErrText). If InitErrMgr is NOT called prior to calling GetSysErrText or GetToolErrText, then those routines, the first time they are called, will call InitErrMgr as InitErrMgr(NULL, NULL, true). The following global may be set to true to allow a C caller to process all strings as Pascal strings:*/ extern Boolean pascalStrings; /* set to true for Pascal strings*//* This should be set PRIOR to calling InitErrMgr. Once set, ALL strings, both those passed to the ErrMgr as filenames and error message inserts, as well as the messages returned by the ErrMgr will be Pascal strings. There is NO guarantee a '\0' byte is at the end of the string. Results are unpredictable if pascalStringsis set false after it has been set true! */ æKY ErrNo.h æFc ErrNo.h æC Synopsis #include <ErrNo.h> extern int errno; extern short MacOSErr; Description Many of the Standard C Library functions can return, in addition to their normal return values, a negative value indicating an error, typically –1. For example, a function returning a character as an int will indicate an error by returning –1, which is not a legitimate ASCII value. (See the Descriptions of individual functions for details.) The external variable errno also provides an error number. Variable errno is not cleared on successful calls, so it should be tested only if the return value indicates an error. The error name appears in brackets following the text in a library function description: for example, “The next attempt to write a nonzero number of bytes will signal an error. [ENOSPC]” Not all possible error numbers are listed for each library function because many errors are possible for most of the calls. Some UNIX operating system error numbers do not apply to Macintosh and are not documented in this manual. Some calls go to the Macintosh ROM and return a value in MacOSErr as well as the value in errno. Table 3-2 is a list of the error numbers and their names as defined in the <ErrNo.h> file. Not all the error numbers listed here will be returned, but they are included in the header file for compatibility. Table 3-2 I/O errors Value Identifier Message Explanation 1 EPERM No permission match An attempt was made to modify a file in some way forbidden except to its creator. 2 ENOENT No such file or directory A file whose filename is specified does not exist, or one of the directories in a pathname does not exist. 3 ENORSRC Resource not found A required resource was not found. This error applies to faccess calls that return tab, font, or print record information. 4 EINTR System service interrupted A requested system call cannot be completed. This error may occur if a request to rename a file is unsuccessful. 5 EIO I/O error Some physical I/O error has occurred. This error may in some cases be signaled on a call following the one to which it actually applies. 6 ENXIO No such device or address I/O on a special file refers to a subdevice that does not exist, or the I/O is beyond the limits of the device. This error may also occur when, for example, no disk is present in a drive. 7 E2BIG Insufficient space for The data to be returned is too large for the space allocated to receive it. 9 EBADF Bad file number Either a file descriptor does not refer to an open file, or a read (or write) request is made to a file that is open only for writing (or reading). 12 ENOMEM Not enough space. The system ran out of memory while the library call was executing. 13 EACCES Permission denied. An attempt was made to access a file in a way forbidden by the protection system. 14 EFAULT Illegal filename. A filename or volume name was too long or otherwise illegal. 15 ENOTBLK Block device required. A non-block file was used when a block device was required. 16 EBUSY Device or resource busy. An attempt was made to mount a volume that was already mounted, or to delete a locked file. 17 EEXIST File exists. An existing file was mentioned in an inappropriate context; for example, open(file, O_CREAT+O_EXCL). 18 EXDEV Cross-device link. A link to a file on another device was attempted. 19 ENODEV No such device. An attempt was made to apply an inappropriate system call to a device; for example, read a write-only device. 20 ENOTDIR Not a directory. An object that is not a directory was specified where a directory is required; for example, in a path prefix. 21 EISDIR Is a directory. An attempt was made to write on a directory. 22 EINVAL Invalid parameter. Some invalid parameter was provided to a library function. 23 ENFILE File table overflow. The system’s table of open files is full, so temporarily a call to open cannot be accepted. 24 EMFILE Too many open files. The system cannot allocate memory to record another open file. 25 ENOTTY Not a typewriter. The specified file isn’t a character file. 26 ETXTBSY Text file busy. An attempt was made to open a file that was already open for writing. 27 EFBIG File too large. The size of a file was larger than the maximum file size. 28 ENOSPC No space left on device. During a write to a file, there is no free space left on the device. 29 ESPIPE Illegal seek. An lseek was issued incorrectly. 30 EROFS Read-only file system. An attempt to modify a file or directory was made on a device mounted for read-only access. 31 EMLINK Too many links. An attempt to delete an open file was made. 33 EDOM Math arg out of domain of func. The argument of a math function is outside the domain of the function. 34 ERANGE Math result not representable. The value of a math function can’t be represented within the machine’s precision. Note Calls that interface to the Macintosh I/O system (such as open, close, read, write, and ioctl) can set the external variable MacOSErr as well as errno on errors. This section documents the errno values. The equivalent Macintosh ROM error-return values set in MacOSErr are documented in the System Error Handler chapter of Inside Macintosh. See also hypot, signal, perror, creat, open, close, read, write, ioctl æKY Errors.h æKL SysError abortErr addRefFailed addResFailed afpAccessDenied afpAuthContinue afpBadIDErr afpBadUAM afpBadVersNum afpBitmapErr afpCallNotSupported afpCantMove afpCantRename afpCatalogChanged afpContainsSharedErr afpDenyConflict afpDiffVolErr afpDirNotEmpty afpDirNotFound afpDiskFull afpEofError afpFileBusy afpFlatVol afpIconTypeError afpIDExists afpIDNotFound afpInsideSharedErr afpInsideTrashErr afpItemNotFound afpLockErr afpMiscErr afpNoMoreLocks afpNoServer afpObjectExists afpObjectLocked afpObjectNotFound afpObjectTypeErr afpParmErr afpPwdExpiredErr afpPwdSameErr afpPwdTooShortErr afpRangeNotLocked afpRangeOverlap afpSameObjectErr afpServerGoingDown afpSessClosed afpTooManyFilesOpen afpUserNotAuth afpVolLocked appIsDaemon appMemFullErr appModeErr aspBadVersNum aspBufTooSmall aspNoAck aspNoMoreSess aspNoServers aspParamErr aspServerBusy aspSessClosed aspSizeErr aspTooMany atpBadRsp atpLenErr authFailErr badATPSkt badBtSlpErr badBuffNum badChannel badCksmErr badDBtSlp badDCksum badEditionFileErr badExtResource badFidErr badFileFormat badFormat badLocNameErr badMDBErr badMovErr badPortNameErr badReqErr badSectionErr badServiceMethodErr badSubPartErr badUnitErr bdNamErr breakRecd buf2SmallErr buffersTooSmall cannotDeferErr cannotMakeContiguousErr CantDecompress cantLoadPickMethodErr cantStepErr catChangedErr cbNotFound CDEFNFnd cDevErr channelBusy channelNotBusy ckSumErr clkRdErr clkWrErr closErr cMatchErr cNoMemErr colorsRequestedErr containerAlreadyOpenWrn containerNotFoundWrn controlErr corErr cProtectErr cRangeErr cResErr cTempMemErr dataVerErr dceExtErr ddpLenErr ddpSktErr desktopDamagedErr destPortErr diffVolErr dInstErr dirFulErr dirNFErr dRemovErr ds32BitMode dsAddressErr dsBadLaunch dsBadPatch dsBadPatchHeader dsBadSANEOpcode dsBadSlotInt dsBadStartupDisk dsBufPtrTooLow dsBusError dsCDEFNotFound dsChkErr dsCoreErr dsDisassemblerInstalled dsExtensionsDisabled dsFinderErr dsForcedQuit dsFPErr dsFSErr dsGreeting dsHD20Installed dsHMenuFindErr dsIllInstErr dsIOCoreErr dsIrqErr dskFulErr dsLineAErr dsLineFErr dsLoadErr dsMacsBugInstalled dsMBarNFnd dsMDEFNotFound dsMemFullErr dsMiscErr dsNeedToWriteBootBlocks dsNoFPU dsNoPackErr dsNoPatch dsNoPk1 dsNoPk2 dsNoPk3 dsNoPk4 dsNoPk5 dsNoPk6 dsNoPk7 dsNotEnoughRAMToBoot dsNotThe1 dsOldSystem dsOvflowErr dsParityErr dsPrivErr dsReinsert dsShutDownOrRestart dsStknHeap dsSwitchOffOrRestart dsSysErr dsSystemFileErr dsTraceErr dsWDEFNotFound dsZeroDivErr dupFNErr editionMgrInitErr envBadVers envNotPresent envVersTooBig eofErr evtNotEnb excessCollsns extFSErr extractErr exUserBreak fBsyErr fidExists fidNotFound firstDskErr fLckdErr fmt1Err fmt2Err fnfErr fnOpnErr fontDecError fontNotDeclared fontNotOutlineErr fontSubErr framingErr fsRnErr gcrOnMFMErr gfpErr guestNotAllowedErr hardwareConfigErr hMenuFindErr hwOverrunErr hwParamErr iIOAbortErr initIWMErr interruptsMaskedErr ioErr lapProtErr lastDskErr localOnlyErr MacOSErr mapReadErr mBarNFnd memAdrErr memAZErr memBCErr memFragErr memFullErr memLockedErr memPCErr memPurErr memROZErr memROZError memROZWarn memSCErr memWZErr menuPrgErr mFulErr multiplePublisherWrn nameTypeErr nbpBuffOvr nbpConfDiff nbpDuplicate nbpNISErr nbpNoConfirm nbpNotFound negZcbFreeErr networkErr nilHandleErr nmTypErr noAdrMkErr noBridgeErr noDataArea noDefaultUserErr noDriveErr noDtaMkErr noGlobalsErr noHardware noHardwareErr noInformErr noMacDskErr noMachineNameErr noMemForPictPlaybackErr noMoreRealTime noMPPErr noNybErr noPortErr noRelErr noResponseErr noScrapErr noSendResp noSessionErr notAFileErr notEnoughBufferSpace notEnoughHardware notEnoughHardwareErr notEnoughMemoryErr notHeldErr notInitErr notLockedErr notLoggedInErr noToolboxNameErr notOpenErr notRegisteredSectionErr notThePublisherWrn noTypeErr noUserNameErr noUserRecErr noUserRefErr nsDrvErr nsStackErr nsvErr offLinErr openErr opWrErr paramErr parityErr permErr pictInfoIDErr pictInfoVerbErr pictInfoVersionErr pictureDataErr pixMapTooDeepErr pmBusyErr pmRecvEndErr pmRecvStartErr pmReplyTOErr pmSendEndErr pmSendStartErr portClosedErr portInUse portNameExistsErr portNotCf posErr prInitErr procNotFound protocolErr prWrErr qErr queueFull rcvrErr readErr readQErr recNotFnd reqAborted reqFailed resAttrErr resFNotFound resNotFound resProblem rfNumErr rgnTooBigErr rgnTooBigError rmvRefFailed rmvResFailed sameFileErr sdmInitErr sdmJTInitErr sdmPRAMInitErr sdmPriInitErr sdmSRTInitErr sectNFErr seekErr selectorErr seNoDB sessClosedErr sessTableErr shutDownAlert siBadDeviceName siBadRefNum siBadSoundInDevice siDeviceBusyErr siHardDriveTooSlow siInitSDTblErr siInitSPTblErr siInitVBLQsErr siInputDeviceErr siInvalidCompression siInvalidSampleRate siInvalidSampleSize siNoBufferSpecified siNoSoundInHardware siUnknownInfoType siUnknownQuality sktClosedErr slotNumErr SlpTypeErr smBadBoardId smBadRefId smBadsList smBadsPtrErr smBLFieldBad smBlkMoveErr smBusErrTO smByteLanesErr smCkStatusErr smCodeRevErr smCPUErr smCRCFail smDisabledSlot smDisDrvrNamErr smDisposePErr smEmptySlot smFHBlkDispErr smFHBlockRdErr smFormatErr smGetDrvrNamErr smGetPRErr smInitStatVErr smInitTblVErr smNewPErr smNilsBlockErr smNoBoardId smNoBoardSRsrc smNoDir smNoGoodOpens smNoJmpTbl smNoMoresRsrcs smNosInfoArray smOffsetErr smPRAMInitErr smPriInitErr smRecNotFnd smReservedErr smResrvErr smRevisionErr smSDMInitErr smSelOOBErr smsGetDrvrErr smSlotOOBErr smsPointerNil smSRTInitErr smSRTOvrFlErr smUnExBusErr spdAdjErr statusErr strUserBreak svDisabled svTempDisable swOverrunErr teScrapSizeErr tk0BadErr tmfoErr tmwdoErr tooManyReqs tooManySkts twoSideErr unimpErr unitEmptyErr unitTblFullErr updPixMemErr userBreak userCanceledErr userRejectErr verErr vLckdErr volGoneErr volOffLinErr volOnLinErr vTypErr WDEFNFnd wPrErr wrgVolTypErr writErr wrPermErr wrUnderrun æKY paramErr æFc Errors.h æT æD paramErr = -50, /*error in user parameter list*/ æC æKY noHardwareErr æFc Errors.h æT æD noHardwareErr = -200, /*Sound Manager Error Returns*/ æC æKY notEnoughHardwareErr æFc Errors.h æT æD notEnoughHardwareErr = -201, /*Sound Manager Error Returns*/ æC æKY userCanceledErr æFc Errors.h æT æD userCanceledErr = -128, æC æKY qErr æFc Errors.h æT æD qErr = -1, /*queue element not found during deletion*/ æC æKY vTypErr æFc Errors.h æT æD vTypErr = -2, /*invalid queue element*/ æC æKY corErr æFc Errors.h æT æD corErr = -3, /*core routine number out of range*/ æC æKY unimpErr æFc Errors.h æT æD unimpErr = -4, /*unimplemented core routine*/ æC æKY SlpTypeErr æFc Errors.h æT æD SlpTypeErr = -5, /*invalid queue element*/ æC æKY seNoDB æFc Errors.h æT æD seNoDB = -8, /*no debugger installed to handle debugger command*/ æC æKY controlErr æFc Errors.h æT æD controlErr = -17, /*I/O System Errors*/ æC æKY statusErr æFc Errors.h æT æD statusErr = -18, /*I/O System Errors*/ æC æKY readErr æFc Errors.h æT æD readErr = -19, /*I/O System Errors*/ æC æKY writErr æFc Errors.h æT æD writErr = -20, /*I/O System Errors*/ æC æKY badUnitErr æFc Errors.h æT æD badUnitErr = -21, /*I/O System Errors*/ æC æKY unitEmptyErr æFc Errors.h æT æD unitEmptyErr = -22, /*I/O System Errors*/ æC æKY openErr æFc Errors.h æT æD openErr = -23, /*I/O System Errors*/ æC æKY closErr æFc Errors.h æT æD closErr = -24, /*I/O System Errors*/ æC æKY dRemovErr æFc Errors.h æT æD dRemovErr = -25, /*tried to remove an open driver*/ æC æKY dInstErr æFc Errors.h æT æD dInstErr = -26, /*DrvrInstall couldn't find driver in resources */ æC æKY abortErr æFc Errors.h æT æD abortErr = -27, /*IO call aborted by KillIO*/ æC æKY iIOAbortErr æFc Errors.h æT æD iIOAbortErr = -27, /*IO abort error (Printing Manager)*/ æC æKY notOpenErr æFc Errors.h æT æD notOpenErr = -28, /*Couldn't rd/wr/ctl/sts cause driver not opened*/ æC æKY unitTblFullErr æFc Errors.h æT æD unitTblFullErr = -29, /*unit table has no more entries*/ æC æKY dceExtErr æFc Errors.h æT æD dceExtErr = -30, /*dce extension error*/ æC æKY slotNumErr æFc Errors.h æT æD slotNumErr = -360, /*invalid slot # error*/ æC æKY gcrOnMFMErr æFc Errors.h æT æD gcrOnMFMErr = -400, /*gcr format on high density media error*/ æC æKY dirFulErr æFc Errors.h æT æD dirFulErr = -33, /*Directory full*/ æC æKY dskFulErr æFc Errors.h æT æD dskFulErr = -34, /*disk full*/ æC æKY nsvErr æFc Errors.h æT æD nsvErr = -35, /*no such volume*/ æC æKY ioErr æFc Errors.h æT æD ioErr = -36, /*I/O error (bummers)*/ æC æKY bdNamErr æFc Errors.h æT æD bdNamErr = -37, /*there may be no bad names in the final system!*/ æC æKY fnOpnErr æFc Errors.h æT æD fnOpnErr = -38, /*File not open*/ æC æKY eofErr æFc Errors.h æT æD eofErr = -39, /*End of file*/ æC æKY posErr æFc Errors.h æT æD posErr = -40, /*tried to position to before start of file (r/w)*/ æC æKY mFulErr æFc Errors.h æT æD mFulErr = -41, /*memory full (open) or file won't fit (load)*/ æC æKY tmfoErr æFc Errors.h æT æD tmfoErr = -42, /*too many files open*/ æC æKY fnfErr æFc Errors.h æT æD fnfErr = -43, /*File not found*/ æC æKY wPrErr æFc Errors.h æT æD wPrErr = -44, /*diskette is write protected.*/ æC æKY fLckdErr æFc Errors.h æT æD fLckdErr = -45, /*file is locked*/ æC æKY vLckdErr æFc Errors.h æT æD vLckdErr = -46, /*volume is locked*/ æC æKY fBsyErr æFc Errors.h æT æD fBsyErr = -47, /*File is busy (delete)*/ æC æKY dupFNErr æFc Errors.h æT æD dupFNErr = -48, /*duplicate filename (rename)*/ æC æKY opWrErr æFc Errors.h æT æD opWrErr = -49, /*file already open with with write permission*/ æC æKY rfNumErr æFc Errors.h æT æD rfNumErr = -51, /*refnum error*/ æC æKY gfpErr æFc Errors.h æT æD gfpErr = -52, /*get file position error*/ æC æKY volOffLinErr æFc Errors.h æT æD volOffLinErr = -53, /*volume not on line error (was Ejected)*/ æC æKY permErr æFc Errors.h æT æD permErr = -54, /*permissions error (on file open)*/ æC æKY volOnLinErr æFc Errors.h æT æD volOnLinErr = -55, /*drive volume already on-line at MountVol*/ æC æKY nsDrvErr æFc Errors.h æT æD nsDrvErr = -56, /*no such drive (tried to mount a bad drive num)*/ æC æKY noMacDskErr æFc Errors.h æT æD noMacDskErr = -57, /*not a mac diskette (sig bytes are wrong)*/ æC æKY extFSErr æFc Errors.h æT æD extFSErr = -58, /*volume in question belongs to an external fs*/ æC æKY fsRnErr æFc Errors.h æT æD fsRnErr = -59, /*file system internal error:during rename the old entry was deleted but could not be restored.*/ æC æKY badMDBErr æFc Errors.h æT æD badMDBErr = -60, /*bad master directory block*/ æC æKY wrPermErr æFc Errors.h æT æD wrPermErr = -61, /*write permissions error*/ æC æKY dirNFErr æFc Errors.h æT æD dirNFErr = -120, /*Directory not found*/ æC æKY tmwdoErr æFc Errors.h æT æD tmwdoErr = -121, /*No free WDCB available*/ æC æKY badMovErr æFc Errors.h æT æD badMovErr = -122, /*Move into offspring error*/ æC æKY wrgVolTypErr æFc Errors.h æT æD wrgVolTypErr = -123, /*Wrong volume type error [operation not supported for MFS]*/ æC æKY volGoneErr æFc Errors.h æT æD volGoneErr = -124, /*Server volume has been disconnected.*/ æC æKY fidNotFound æFc Errors.h æT æD fidNotFound = -1300, /*no file thread exists.*/ æC æKY fidExists æFc Errors.h æT æD fidExists = -1301, /*file id already exists*/ æC æKY notAFileErr æFc Errors.h æT æD notAFileErr = -1302, /*directory specified*/ æC æKY diffVolErr æFc Errors.h æT æD diffVolErr = -1303, /*files on different volumes*/ æC æKY catChangedErr æFc Errors.h æT æD catChangedErr = -1304, /*the catalog has been modified*/ æC æKY desktopDamagedErr æFc Errors.h æT æD desktopDamagedErr = -1305, /*desktop database files are corrupted*/ æC æKY sameFileErr æFc Errors.h æT æD sameFileErr = -1306, /*can't exchange a file with itself*/ æC æKY badFidErr æFc Errors.h æT æD badFidErr = -1307, /*file id is dangling or doesn't match with the file number*/ æC æKY envNotPresent æFc Errors.h æT æD envNotPresent = -5500, /*returned by glue.*/ æC æKY envBadVers æFc Errors.h æT æD envBadVers = -5501, /*Version non-positive*/ æC æKY envVersTooBig æFc Errors.h æT æD envVersTooBig = -5502, /*Version bigger than call can handle*/ æC æKY fontDecError æFc Errors.h æT æD fontDecError = -64, /*error during font declaration*/ æC æKY fontNotDeclared æFc Errors.h æT æD fontNotDeclared = -65, /*font not declared*/ æC æKY fontSubErr æFc Errors.h æT æD fontSubErr = -66, /*font substitution occured*/ æC æKY fontNotOutlineErr æFc Errors.h æT æD fontNotOutlineErr = -32615, /*bitmap font passed to routine that does outlines only*/ æC æKY firstDskErr æFc Errors.h æT æD firstDskErr = -84, /*I/O System Errors*/ æC æKY lastDskErr æFc Errors.h æT æD lastDskErr = -64, /*I/O System Errors*/ æC æKY noDriveErr æFc Errors.h æT æD noDriveErr = -64, /*drive not installed*/ æC æKY offLinErr æFc Errors.h æT æD offLinErr = -65, /*r/w requested for an off-line drive*/ æC æKY noNybErr æFc Errors.h æT æD noNybErr = -66, /*couldn't find 5 nybbles in 200 tries*/ æC æKY noAdrMkErr æFc Errors.h æT æD noAdrMkErr = -67, /*couldn't find valid addr mark*/ æC æKY dataVerErr æFc Errors.h æT æD dataVerErr = -68, /*read verify compare failed*/ æC æKY badCksmErr æFc Errors.h æT æD badCksmErr = -69, /*addr mark checksum didn't check*/ æC æKY badBtSlpErr æFc Errors.h æT æD badBtSlpErr = -70, /*bad addr mark bit slip nibbles*/ æC æKY noDtaMkErr æFc Errors.h æT æD noDtaMkErr = -71, /*couldn't find a data mark header*/ æC æKY badDCksum æFc Errors.h æT æD badDCksum = -72, /*bad data mark checksum*/ æC æKY badDBtSlp æFc Errors.h æT æD badDBtSlp = -73, /*bad data mark bit slip nibbles*/ æC æKY wrUnderrun æFc Errors.h æT æD wrUnderrun = -74, /*write underrun occurred*/ æC æKY cantStepErr æFc Errors.h æT æD cantStepErr = -75, /*step handshake failed*/ æC æKY tk0BadErr æFc Errors.h æT æD tk0BadErr = -76, /*track 0 detect doesn't change*/ æC æKY initIWMErr æFc Errors.h æT æD initIWMErr = -77, /*unable to initialize IWM*/ æC æKY twoSideErr æFc Errors.h æT æD twoSideErr = -78, /*tried to read 2nd side on a 1-sided drive*/ æC æKY spdAdjErr æFc Errors.h æT æD spdAdjErr = -79, /*unable to correctly adjust disk speed*/ æC æKY seekErr æFc Errors.h æT æD seekErr = -80, /*track number wrong on address mark*/ æC æKY sectNFErr æFc Errors.h æT æD sectNFErr = -81, /*sector number never found on a track*/ æC æKY fmt1Err æFc Errors.h æT æD fmt1Err = -82, /*can't find sector 0 after track format*/ æC æKY fmt2Err æFc Errors.h æT æD fmt2Err = -83, /*can't get enough sync*/ æC æKY verErr æFc Errors.h æT æD verErr = -84, /*track failed to verify*/ æC æKY clkRdErr æFc Errors.h æT æD clkRdErr = -85, /*unable to read same clock value twice*/ æC æKY clkWrErr æFc Errors.h æT æD clkWrErr = -86, /*time written did not verify*/ æC æKY prWrErr æFc Errors.h æT æD prWrErr = -87, /*parameter ram written didn't read-verify*/ æC æKY prInitErr æFc Errors.h æT æD prInitErr = -88, /*InitUtil found the parameter ram uninitialized*/ æC æKY rcvrErr æFc Errors.h æT æD rcvrErr = -89, /*SCC receiver error (framing; parity; OR)*/ æC æKY breakRecd æFc Errors.h æT æD breakRecd = -90, /*Break received (SCC)*/ æC æKY pmBusyErr æFc Errors.h æT æD pmBusyErr = -13000, /*Power Mgr never ready to start handshake*/ æC æKY pmReplyTOErr æFc Errors.h æT æD pmReplyTOErr = -13001, /*Timed out waiting for reply*/ æC æKY pmSendStartErr æFc Errors.h æT æD pmSendStartErr = -13002, /*during send, pmgr did not start hs*/ æC æKY pmSendEndErr æFc Errors.h æT æD pmSendEndErr = -13003, /*during send, pmgr did not finish hs*/ æC æKY pmRecvStartErr æFc Errors.h æT æD pmRecvStartErr = -13004, /*during receive, pmgr did not start hs*/ æC æKY pmRecvEndErr æFc Errors.h æT æD pmRecvEndErr = -13005, /*during receive, pmgr did not finish hs configured for this connection*/ æC æKY noScrapErr æFc Errors.h æT æD noScrapErr = -100, /*No scrap exists error*/ æC æKY noTypeErr æFc Errors.h æT æD noTypeErr = -102, /*No object of that type in scrap*/ æC æKY memROZWarn æFc Errors.h æT æD memROZWarn = -99, /*soft error in ROZ*/ æC æKY memROZError æFc Errors.h æT æD memROZError = -99, /*hard error in ROZ*/ æC æKY memROZErr æFc Errors.h æT æD memROZErr = -99, /*hard error in ROZ*/ æC æKY memFullErr æFc Errors.h æT æD memFullErr = -108, /*Not enough room in heap zone*/ æC æKY nilHandleErr æFc Errors.h æT æD nilHandleErr = -109, /*Master Pointer was NIL in HandleZone or other*/ æC æKY memWZErr æFc Errors.h æT æD memWZErr = -111, /*WhichZone failed (applied to free block)*/ æC æKY memPurErr æFc Errors.h æT æD memPurErr = -112, /*trying to purge a locked or non-purgeable block*/ æC æKY memAdrErr æFc Errors.h æT æD memAdrErr = -110, /*address was odd; or out of range*/ æC æKY memAZErr æFc Errors.h æT æD memAZErr = -113, /*Address in zone check failed*/ æC æKY memPCErr æFc Errors.h æT æD memPCErr = -114, /*Pointer Check failed*/ æC æKY memBCErr æFc Errors.h æT æD memBCErr = -115, /*Block Check failed*/ æC æKY memSCErr æFc Errors.h æT æD memSCErr = -116, /*Size Check failed*/ æC æKY memLockedErr æFc Errors.h æT æD memLockedErr = -117, /*trying to move a locked block (MoveHHi)*/ æC æKY resNotFound æFc Errors.h æT æD resNotFound = -192, /*Resource not found*/ æC æKY resFNotFound æFc Errors.h æT æD resFNotFound = -193, /*Resource file not found*/ æC æKY addResFailed æFc Errors.h æT æD addResFailed = -194, /*AddResource failed*/ æC æKY addRefFailed æFc Errors.h æT æD addRefFailed = -195, /*AddReference failed*/ æC æKY rmvResFailed æFc Errors.h æT æD rmvResFailed = -196, /*RmveResource failed*/ æC æKY rmvRefFailed æFc Errors.h æT æD rmvRefFailed = -197, /*RmveReference failed*/ æC æKY resAttrErr æFc Errors.h æT æD resAttrErr = -198, /*attribute inconsistent with operation*/ æC æKY mapReadErr æFc Errors.h æT æD mapReadErr = -199, /*map inconsistent with operation*/ æC æKY CantDecompress æFc Errors.h æT æD CantDecompress = -186, /*resource bent ("the bends") - can't decompress a compressed resource*/ æC æKY badExtResource æFc Errors.h æT æD badExtResource = -185, /*extended resource has a bad format.*/ æC æKY evtNotEnb æFc Errors.h æT æD evtNotEnb = 1, /*event not enabled at PostEvent*/ æC æKY noMemForPictPlaybackErr æFc Errors.h æT æD noMemForPictPlaybackErr = -145, æC æKY rgnTooBigError æFc Errors.h æT æD rgnTooBigError = -147, æC æKY pixMapTooDeepErr æFc Errors.h æT æD pixMapTooDeepErr = -148, æC æKY nsStackErr æFc Errors.h æT æD nsStackErr = -149, æC æKY cMatchErr æFc Errors.h æT æD cMatchErr = -150, /*Color2Index failed to find an index*/ æC æKY cTempMemErr æFc Errors.h æT æD cTempMemErr = -151, /*failed to allocate memory for temporary structures*/ æC æKY cNoMemErr æFc Errors.h æT æD cNoMemErr = -152, /*failed to allocate memory for structure*/ æC æKY cRangeErr æFc Errors.h æT æD cRangeErr = -153, /*range error on colorTable request*/ æC æKY cProtectErr æFc Errors.h æT æD cProtectErr = -154, /*colorTable entry protection violation*/ æC æKY cDevErr æFc Errors.h æT æD cDevErr = -155, /*invalid type of graphics device*/ æC æKY cResErr æFc Errors.h æT æD cResErr = -156, /*invalid resolution for MakeITable*/ æC æKY rgnTooBigErr æFc Errors.h æT æD rgnTooBigErr = -500, æC æKY updPixMemErr æFc Errors.h æT æD updPixMemErr = -125, /*insufficient memory to update a pixmap*/ æC /*insuffiFc Errors.h CIent memory to update a pixmap*/ æKY pictInfoVersionErr æFc Errors.h æT æD pictInfoVersionErr = -11000, /* wrong version of the PictInfo structure */ æC æKY pictInfoIDErr æFc Errors.h æT æD pictInfoIDErr = -11001, /* the internal consistancy check for the PictInfoID is wrong */ æC æKY pictInfoVerbErr æFc Errors.h æT æD pictInfoVerbErr = -11002, /* the passed verb was invalid */ æC æKY cantLoadPickMethodErr æFc Errors.h æT æD cantLoadPickMethodErr = -11003, /* unable to load the custom pick proc */ æC æKY colorsRequestedErr æFc Errors.h æT æD colorsRequestedErr = -11004, /* the number of colors requested was illegal */ æC æKY pictureDataErr æFc Errors.h æT æD pictureDataErr = -11005, /* the picture data was invalid */ æC æKY noHardware æFc Errors.h æT æD noHardware = noHardwareErr, /* *** obsolete spelling */ æC æKY notEnoughHardware æFc Errors.h æT æD notEnoughHardware = notEnoughHardwareErr, /* *** obsolete spelling */ æC æKY queueFull æFc Errors.h æT æD queueFull = -203, /*Sound Manager Error Returns*/ æC æKY resProblem æFc Errors.h æT æD resProblem = -204, /*Sound Manager Error Returns*/ æC æKY badChannel æFc Errors.h æT æD badChannel = -205, /*Sound Manager Error Returns*/ æC æKY badFormat æFc Errors.h æT æD badFormat = -206, /*Sound Manager Error Returns*/ æC æKY notEnoughBufferSpace æFc Errors.h æT æD notEnoughBufferSpace = -207, /* could not allocate enough memory */ æC æKY badFileFormat æFc Errors.h æT æD badFileFormat = -208, /* was not type AIFF or was of bad format,corrupt */ æC æKY channelBusy æFc Errors.h æT æD channelBusy = -209, /* the Channel is being used for a PFD already */ æC æKY buffersTooSmall æFc Errors.h æT æD buffersTooSmall = -210, /* can not operate in the memory allowed */ æC æKY channelNotBusy æFc Errors.h æT æD channelNotBusy = -211, æC æKY noMoreRealTime æFc Errors.h æT æD noMoreRealTime = -212, /* not enough CPU cycles left to add another task */ æC æKY siNoSoundInHardware æFc Errors.h æT æD siNoSoundInHardware = -220, /*no Sound Input hardware*/ æC æKY siBadSoundInDevice æFc Errors.h æT æD siBadSoundInDevice = -221, /*invalid index passed to SoundInGetIndexedDevice*/ æC æKY siNoBufferSpecified æFc Errors.h æT æD siNoBufferSpecified = -222, /*returned by synchronous SPBRecord if nil buffer passed*/ æC æKY siInvalidCompression æFc Errors.h æT æD siInvalidCompression = -223, /*invalid compression type*/ æC æKY siHardDriveTooSlow æFc Errors.h æT æD siHardDriveTooSlow = -224, /*hard drive too slow to record to disk*/ æC æKY siInvalidSampleRate æFc Errors.h æT æD siInvalidSampleRate = -225, /*invalid sample rate*/ æC æKY siInvalidSampleSize æFc Errors.h æT æD siInvalidSampleSize = -226, /*invalid sample size*/ æC æKY siDeviceBusyErr æFc Errors.h æT æD siDeviceBusyErr = -227, /*input device already in use*/ æC æKY siBadDeviceName æFc Errors.h æT æD siBadDeviceName = -228, /*input device could not be opened*/ æC æKY siBadRefNum æFc Errors.h æT æD siBadRefNum = -229, /*invalid input device reference number*/ æC æKY siInputDeviceErr æFc Errors.h æT æD siInputDeviceErr = -230, /*input device hardware failure*/ æC æKY siUnknownInfoType æFc Errors.h æT æD siUnknownInfoType = -231, /*invalid info type selector (returned by driver)*/ æC æKY siUnknownQuality æFc Errors.h æT æD siUnknownQuality = -232, /*invalid quality selector (returned by driver)*/ æC æKY nmTypErr æFc Errors.h æT æD nmTypErr = -299, /*wrong queue type*/ æC æKY siInitSDTblErr æFc Errors.h æT æD siInitSDTblErr = 1, /*slot int dispatch table could not be initialized.*/ æC æKY siInitVBLQsErr æFc Errors.h æT æD siInitVBLQsErr = 2, /*VBLqueues for all slots could not be initialized.*/ æC æKY siInitSPTblErr æFc Errors.h æT æD siInitSPTblErr = 3, /*slot priority table could not be initialized.*/ æC æKY sdmJTInitErr æFc Errors.h æT æD sdmJTInitErr = 10, /*SDM Jump Table could not be initialized.*/ æC æKY sdmInitErr æFc Errors.h æT æD sdmInitErr = 11, /*SDM could not be initialized.*/ æC æKY sdmSRTInitErr æFc Errors.h æT æD sdmSRTInitErr = 12, /*Slot Resource Table could not be initialized.*/ æC æKY sdmPRAMInitErr æFc Errors.h æT æD sdmPRAMInitErr = 13, /*Slot PRAM could not be initialized.*/ æC æKY sdmPriInitErr æFc Errors.h æT æD sdmPriInitErr = 14, /*Cards could not be initialized.*/ æC æKY smSDMInitErr æFc Errors.h æT æD smSDMInitErr = -290, /*Error; SDM could not be initialized.*/ æC æKY smSRTInitErr æFc Errors.h æT æD smSRTInitErr = -291, /*Error; Slot Resource Table could not be initialized.*/ æC æKY smPRAMInitErr æFc Errors.h æT æD smPRAMInitErr = -292, /*Error; Slot Resource Table could not be initialized.*/ æC æKY smPriInitErr æFc Errors.h æT æD smPriInitErr = -293, /*Error; Cards could not be initialized.*/ æC æKY smEmptySlot æFc Errors.h æT æD smEmptySlot = -300, /*No card in slot*/ æC æKY smCRCFail æFc Errors.h æT æD smCRCFail = -301, /*CRC check failed for declaration data*/ æC æKY smFormatErr æFc Errors.h æT æD smFormatErr = -302, /*FHeader Format is not Apple's*/ æC æKY smRevisionErr æFc Errors.h æT æD smRevisionErr = -303, /*Wrong revison level*/ æC æKY smNoDir æFc Errors.h æT æD smNoDir = -304, /*Directory offset is Nil */ æC æKY smDisabledSlot æFc Errors.h æT æD smDisabledSlot = -305, /*This slot is disabled (-305 use to be smLWTstBad)*/ æC æKY smNosInfoArray æFc Errors.h æT æD smNosInfoArray = -306, /*No sInfoArray. Memory Mgr error.*/ æC æKY smResrvErr æFc Errors.h æT æD smResrvErr = -307, /*Fatal reserved error. Resreved field <> 0.*/ æC æKY smUnExBusErr æFc Errors.h æT æD smUnExBusErr = -308, /*Unexpected BusError*/ æC æKY smBLFieldBad æFc Errors.h æT æD smBLFieldBad = -309, /*ByteLanes field was bad.*/ æC æKY smFHBlockRdErr æFc Errors.h æT æD smFHBlockRdErr = -310, /*Error occured during _sGetFHeader.*/ æC æKY smFHBlkDispErr æFc Errors.h æT æD smFHBlkDispErr = -311, /*Error occured during _sDisposePtr (Dispose of FHeader block).*/ æC æKY smDisposePErr æFc Errors.h æT æD smDisposePErr = -312, /*_DisposePointer error*/ æC æKY smNoBoardSRsrc æFc Errors.h æT æD smNoBoardSRsrc = -313, /*No Board sResource.*/ æC æKY smGetPRErr æFc Errors.h æT æD smGetPRErr = -314, /*Error occured during _sGetPRAMRec (See SIMStatus).*/ æC æKY smNoBoardId æFc Errors.h æT æD smNoBoardId = -315, /*No Board Id.*/ æC æKY smInitStatVErr æFc Errors.h æT æD smInitStatVErr = -316, /*The InitStatusV field was negative after primary or secondary init.*/ æC æKY smInitTblVErr æFc Errors.h æT æD smInitTblVErr = -317, /*An error occured while trying to initialize the Slot Resource Table.*/ æC æKY smNoJmpTbl æFc Errors.h æT æD smNoJmpTbl = -318, /*SDM jump table could not be created.*/ æC æKY smBadBoardId æFc Errors.h æT æD smBadBoardId = -319, /*BoardId was wrong; re-init the PRAM record.*/ æC æKY smBusErrTO æFc Errors.h æT æD smBusErrTO = -320, /*BusError time out.*/ æC æKY svTempDisable æFc Errors.h æT æD svTempDisable = -32768, /*Temporarily disable card but run primary init.*/ æC æKY svDisabled æFc Errors.h æT æD svDisabled = -32640, /*Reserve range -32640 to -32768 for Apple temp disables.*/ æC æKY smBadRefId æFc Errors.h æT æD smBadRefId = -330, /*Reference Id not found in List*/ æC æKY smBadsList æFc Errors.h æT æD smBadsList = -331, /*Bad sList: Id1 < Id2 < Id3 ...format is not followed.*/ æC æKY smReservedErr æFc Errors.h æT æD smReservedErr = -332, /*Reserved field not zero*/ æC æKY smCodeRevErr æFc Errors.h æT æD smCodeRevErr = -333, /*Code revision is wrong*/ æC æKY smCPUErr æFc Errors.h æT æD smCPUErr = -334, /*Code revision is wrong*/ æC æKY smsPointerNil æFc Errors.h æT æD smsPointerNil = -335, /*LPointer is nil From sOffsetData. If this error occurs; check sInfo rec for more information.*/ æC æKY smNilsBlockErr æFc Errors.h æT æD smNilsBlockErr = -336, /*Nil sBlock error (Dont allocate and try to use a nil sBlock)*/ æC æKY smSlotOOBErr æFc Errors.h æT æD smSlotOOBErr = -337, /*Slot out of bounds error*/ æC æKY smSelOOBErr æFc Errors.h æT æD smSelOOBErr = -338, /*Selector out of bounds error*/ æC æKY smNewPErr æFc Errors.h æT æD smNewPErr = -339, /*_NewPtr error*/ æC æKY smBlkMoveErr æFc Errors.h æT æD smBlkMoveErr = -340, /*_BlockMove error*/ æC æKY smCkStatusErr æFc Errors.h æT æD smCkStatusErr = -341, /*Status of slot = fail.*/ æC æKY smGetDrvrNamErr æFc Errors.h æT æD smGetDrvrNamErr = -342, /*Error occured during _sGetDrvrName.*/ æC æKY smDisDrvrNamErr æFc Errors.h æT æD smDisDrvrNamErr = -343, /*Error occured during _sDisDrvrName.*/ æC æKY smNoMoresRsrcs æFc Errors.h æT æD smNoMoresRsrcs = -344, /*No more sResources*/ æC æKY smsGetDrvrErr æFc Errors.h æT æD smsGetDrvrErr = -345, /*Error occurred during _sGetDriver.*/ æC æKY smBadsPtrErr æFc Errors.h æT æD smBadsPtrErr = -346, /*Bad pointer was passed to sCalcsPointer*/ æC æKY smByteLanesErr æFc Errors.h æT æD smByteLanesErr = -347, /*NumByteLanes was determined to be zero.*/ æC æKY smOffsetErr æFc Errors.h æT æD smOffsetErr = -348, /*Offset was too big (temporary error*/ æC æKY smNoGoodOpens æFc Errors.h æT æD smNoGoodOpens = -349, /*No opens were successfull in the loop.*/ æC æKY smSRTOvrFlErr æFc Errors.h æT æD smSRTOvrFlErr = -350, /*SRT over flow.*/ æC æKY smRecNotFnd æFc Errors.h æT æD smRecNotFnd = -351, /*Record not found in the SRT.*/ æC æKY editionMgrInitErr æFc Errors.h æT æD editionMgrInitErr = -450, /*edition manager not inited by this app*/ æC æKY badSectionErr æFc Errors.h æT æD badSectionErr = -451, /*not a valid SectionRecord*/ æC æKY notRegisteredSectionErr æFc Errors.h æT æD notRegisteredSectionErr = -452, /*not a registered SectionRecord*/ æC æKY badEditionFileErr æFc Errors.h æT æD badEditionFileErr = -453, /*edition file is corrupt*/ æC æKY badSubPartErr æFc Errors.h æT æD badSubPartErr = -454, /*can not use sub parts in this release*/ æC æKY multiplePublisherWrn æFc Errors.h æT æD multiplePublisherWrn = -460, /*A Publisher is already registered for that container*/ æC æKY containerNotFoundWrn æFc Errors.h æT æD containerNotFoundWrn = -461, /*could not find editionContainer at this time*/ æC æKY containerAlreadyOpenWrn æFc Errors.h æT æD containerAlreadyOpenWrn = -462, /*container already opened by this section*/ æC æKY notThePublisherWrn æFc Errors.h æT æD notThePublisherWrn = -463, /*not the first registered publisher for that container*/ æC æKY teScrapSizeErr æFc Errors.h æT æD teScrapSizeErr = -501, /*scrap item too big for text edit record*/ æC æKY hwParamErr æFc Errors.h æT æD hwParamErr = -502, /*bad selector for _HWPriv*/ æC æKY procNotFound æFc Errors.h æT æD procNotFound = -600, /* no eligible process with specified descriptor */ æC æKY memFragErr æFc Errors.h æT æD memFragErr = -601, /* not enough room to launch app w/special requirements */ æC æKY appModeErr æFc Errors.h æT æD appModeErr = -602, /* memory mode is 32-bit, but app not 32-bit clean */ æC æKY protocolErr æFc Errors.h æT æD protocolErr = -603, /* app made module calls in improper order */ æC æKY hardwareConfigErr æFc Errors.h æT æD hardwareConfigErr = -604, /* hardware configuration not correct for call */ æC æKY appMemFullErr æFc Errors.h æT æD appMemFullErr = -605, /* application SIZE not big enough for launch */ æC æKY appIsDaemon æFc Errors.h æT æD appIsDaemon = -606, /* app is BG-only, and launch flags disallow this */ æC æKY notEnoughMemoryErr æFc Errors.h æT æD notEnoughMemoryErr = -620, /*insufficient physical memory*/ æC æKY notHeldErr æFc Errors.h æT æD notHeldErr = -621, /*specified range of memory is not held*/ æC æKY cannotMakeContiguousErr æFc Errors.h æT æD cannotMakeContiguousErr = -622, /*cannot make specified range contiguous*/ æC æKY notLockedErr æFc Errors.h æT æD notLockedErr = -623, /*specified range of memory is not locked*/ æC æKY interruptsMaskedErr æFc Errors.h æT æD interruptsMaskedErr = -624, /*don’t call with interrupts masked*/ æC æKY cannotDeferErr æFc Errors.h æT æD cannotDeferErr = -625, /*unable to defer additional functions*/ æC æKY ddpSktErr æFc Errors.h æT æD ddpSktErr = -91, /*error in soket number*/ æC æKY ddpLenErr æFc Errors.h æT æD ddpLenErr = -92, /*data length too big*/ æC æKY noBridgeErr æFc Errors.h æT æD noBridgeErr = -93, /*no network bridge for non-local send*/ æC æKY lapProtErr æFc Errors.h æT æD lapProtErr = -94, /*error in attaching/detaching protocol*/ æC æKY excessCollsns æFc Errors.h æT æD excessCollsns = -95, /*excessive collisions on write*/ æC æKY portInUse æFc Errors.h æT æD portInUse = -97, /*driver Open error code (port is in use)*/ æC æKY portNotCf æFc Errors.h æT æD portNotCf = -98, /*driver Open error code (parameter RAM not configured for this connection)*/ æC æKY nbpBuffOvr æFc Errors.h æT æD nbpBuffOvr = -1024, /*Buffer overflow in LookupName*/ æC æKY nbpNoConfirm æFc Errors.h æT æD nbpNoConfirm = -1025, æC æKY nbpConfDiff æFc Errors.h æT æD nbpConfDiff = -1026, /*Name confirmed at different socket*/ æC æKY nbpDuplicate æFc Errors.h æT æD nbpDuplicate = -1027, /*Duplicate name exists already*/ æC æKY nbpNotFound æFc Errors.h æT æD nbpNotFound = -1028, /*Name not found on remove*/ æC æKY nbpNISErr æFc Errors.h æT æD nbpNISErr = -1029, /*Error trying to open the NIS*/ æC æKY aspBadVersNum æFc Errors.h æT æD aspBadVersNum = -1066, /*Server cannot support this ASP version*/ æC æKY aspBufTooSmall æFc Errors.h æT æD aspBufTooSmall = -1067, /*Buffer too small*/ æC æKY aspNoMoreSess æFc Errors.h æT æD aspNoMoreSess = -1068, /*No more sessions on server*/ æC æKY aspNoServers æFc Errors.h æT æD aspNoServers = -1069, /*No servers at that address*/ æC æKY aspParamErr æFc Errors.h æT æD aspParamErr = -1070, /*Parameter error*/ æC æKY aspServerBusy æFc Errors.h æT æD aspServerBusy = -1071, /*Server cannot open another session*/ æC æKY aspSessClosed æFc Errors.h æT æD aspSessClosed = -1072, /*Session closed*/ æC æKY aspSizeErr æFc Errors.h æT æD aspSizeErr = -1073, /*Command block too big*/ æC æKY aspTooMany æFc Errors.h æT æD aspTooMany = -1074, /*Too many clients (server error)*/ æC æKY aspNoAck æFc Errors.h æT æD aspNoAck = -1075, /*No ack on attention request (server err)*/ æC æKY reqFailed æFc Errors.h æT æD reqFailed = -1096, æC æKY tooManyReqs æFc Errors.h æT æD tooManyReqs = -1097, æC æKY tooManySkts æFc Errors.h æT æD tooManySkts = -1098, æC æKY badATPSkt æFc Errors.h æT æD badATPSkt = -1099, æC æKY badBuffNum æFc Errors.h æT æD badBuffNum = -1100, æC æKY noRelErr æFc Errors.h æT æD noRelErr = -1101, æC æKY cbNotFound æFc Errors.h æT æD cbNotFound = -1102, æC æKY noSendResp æFc Errors.h æT æD noSendResp = -1103, æC æKY noDataArea æFc Errors.h æT æD noDataArea = -1104, æC æKY reqAborted æFc Errors.h æT æD reqAborted = -1105, æC æKY buf2SmallErr æFc Errors.h æT æD buf2SmallErr = -3101, æC æKY noMPPErr æFc Errors.h æT æD noMPPErr = -3102, æC æKY ckSumErr æFc Errors.h æT æD ckSumErr = -3103, æC æKY extractErr æFc Errors.h æT æD extractErr = -3104, æC æKY readQErr æFc Errors.h æT æD readQErr = -3105, æC æKY atpLenErr æFc Errors.h æT æD atpLenErr = -3106, æC æKY atpBadRsp æFc Errors.h æT æD atpBadRsp = -3107, æC æKY recNotFnd æFc Errors.h æT æD recNotFnd = -3108, æC æKY sktClosedErr æFc Errors.h æT æD sktClosedErr = -3109, æC æKY afpAccessDenied æFc Errors.h æT æD afpAccessDenied = -5000, æC æKY afpAuthContinue æFc Errors.h æT æD afpAuthContinue = -5001, æC æKY afpBadUAM æFc Errors.h æT æD afpBadUAM = -5002, æC æKY afpBadVersNum æFc Errors.h æT æD afpBadVersNum = -5003, æC æKY afpBitmapErr æFc Errors.h æT æD afpBitmapErr = -5004, æC æKY afpCantMove æFc Errors.h æT æD afpCantMove = -5005, æC æKY afpDenyConflict æFc Errors.h æT æD afpDenyConflict = -5006, æC æKY afpDirNotEmpty æFc Errors.h æT æD afpDirNotEmpty = -5007, æC æKY afpDiskFull æFc Errors.h æT æD afpDiskFull = -5008, æC æKY afpEofError æFc Errors.h æT æD afpEofError = -5009, æC æKY afpFileBusy æFc Errors.h æT æD afpFileBusy = -5010, æC æKY afpFlatVol æFc Errors.h æT æD afpFlatVol = -5011, æC æKY afpItemNotFound æFc Errors.h æT æD afpItemNotFound = -5012, æC æKY afpLockErr æFc Errors.h æT æD afpLockErr = -5013, æC æKY afpMiscErr æFc Errors.h æT æD afpMiscErr = -5014, æC æKY afpNoMoreLocks æFc Errors.h æT æD afpNoMoreLocks = -5015, æC æKY afpNoServer æFc Errors.h æT æD afpNoServer = -5016, æC æKY afpObjectExists æFc Errors.h æT æD afpObjectExists = -5017, æC æKY afpObjectNotFound æFc Errors.h æT æD afpObjectNotFound = -5018, æC æKY afpParmErr æFc Errors.h æT æD afpParmErr = -5019, æC æKY afpRangeNotLocked æFc Errors.h æT æD afpRangeNotLocked = -5020, æC æKY afpRangeOverlap æFc Errors.h æT æD afpRangeOverlap = -5021, æC æKY afpSessClosed æFc Errors.h æT æD afpSessClosed = -5022, æC æKY afpUserNotAuth æFc Errors.h æT æD afpUserNotAuth = -5023, æC æKY afpCallNotSupported æFc Errors.h æT æD afpCallNotSupported = -5024, æC æKY afpObjectTypeErr æFc Errors.h æT æD afpObjectTypeErr = -5025, æC æKY afpTooManyFilesOpen æFc Errors.h æT æD afpTooManyFilesOpen = -5026, æC æKY afpServerGoingDown æFc Errors.h æT æD afpServerGoingDown = -5027, æC æKY afpCantRename æFc Errors.h æT æD afpCantRename = -5028, æC æKY afpDirNotFound æFc Errors.h æT æD afpDirNotFound = -5029, æC æKY afpIconTypeError æFc Errors.h æT æD afpIconTypeError = -5030, æC æKY afpVolLocked æFc Errors.h æT æD afpVolLocked = -5031, /*Volume is Read-Only*/ æC æKY afpObjectLocked æFc Errors.h æT æD afpObjectLocked = -5032, /*Object is M/R/D/W inhibited*/ æC æKY afpContainsSharedErr æFc Errors.h æT æD afpContainsSharedErr = -5033, /*$FFFFEC57 the folder being shared contains a shared folder */ æC æKY afpIDNotFound æFc Errors.h æT æD afpIDNotFound = -5034, /*$FFFFEC56*/ æC æKY afpIDExists æFc Errors.h æT æD afpIDExists = -5035, /*$FFFFEC55*/ æC æKY afpDiffVolErr æFc Errors.h æT æD afpDiffVolErr = -5036, /*$FFFFEC54*/ æC æKY afpCatalogChanged æFc Errors.h æT æD afpCatalogChanged = -5037, /*$FFFFEC53*/ æC æKY afpSameObjectErr æFc Errors.h æT æD afpSameObjectErr = -5038, /*$FFFFEC52*/ æC æKY afpBadIDErr æFc Errors.h æT æD afpBadIDErr = -5039, /*$FFFFEC51*/ æC æKY afpPwdSameErr æFc Errors.h æT æD afpPwdSameErr = -5040, /*$FFFFEC50 someone tried to change their password to the same password on a mantadory password change */ æC æKY afpPwdTooShortErr æFc Errors.h æT æD afpPwdTooShortErr = -5041, /*$FFFFEC4F the password being set is too short: there is a minimum length that must be met or exceeded */ æC æKY afpPwdExpiredErr æFc Errors.h æT æD afpPwdExpiredErr = -5042, /*$FFFFEC4E the password being used is too old: this requires the user to change the password before log-in can continue */ æC æKY afpInsideSharedErr æFc Errors.h æT æD afpInsideSharedErr = -5043, /*$FFFFEC4D the folder being shared is inside a shared folder OR the folder contains a shared folder and is being moved into a shared folder OR the folder contains a shared folder and is being moved into the descendent of a shared folder. */ æC æKY afpInsideTrashErr æFc Errors.h æT æD afpInsideTrashErr = -5044, /*$FFFFEC4C the folder being shared is inside the trash folder OR the shared folder is being moved into the trash folder OR the folder is being moved to the trash and it contains a shared folder */ æC æKY notInitErr æFc Errors.h æT æD notInitErr = -900, /* PPCToolBox not initialized */ æC æKY nameTypeErr æFc Errors.h æT æD nameTypeErr = -902, /* Invalid or inappropriate locationKindSelector in locationName */ æC æKY noPortErr æFc Errors.h æT æD noPortErr = -903, /* Unable to open port or bad portRefNum */ æC æKY noGlobalsErr æFc Errors.h æT æD noGlobalsErr = -904, /* The system is hosed, better re-boot */ æC æKY localOnlyErr æFc Errors.h æT æD localOnlyErr = -905, /* Network activity is currently disabled */ æC æKY destPortErr æFc Errors.h æT æD destPortErr = -906, /* Port does not exist at destination */ æC æKY sessTableErr æFc Errors.h æT æD sessTableErr = -907, /* Out of session tables, try again later */ æC æKY noSessionErr æFc Errors.h æT æD noSessionErr = -908, /* Invalid session reference number */ æC æKY badReqErr æFc Errors.h æT æD badReqErr = -909, /* bad parameter or invalid state for operation */ æC æKY portNameExistsErr æFc Errors.h æT æD portNameExistsErr = -910, /* port is already open (perhaps in another app) */ æC æKY noUserNameErr æFc Errors.h æT æD noUserNameErr = -911, /* user name unknown on destination machine */ æC æKY userRejectErr æFc Errors.h æT æD userRejectErr = -912, /* Destination rejected the session request */ æC æKY noMachineNameErr æFc Errors.h æT æD noMachineNameErr = -913, /* user hasn't named his Macintosh in the Network Setup Control Panel */ æC æKY noToolboxNameErr æFc Errors.h æT æD noToolboxNameErr = -914, /* A system resource is missing, not too likely */ æC æKY noResponseErr æFc Errors.h æT æD noResponseErr = -915, /* unable to contact destination */ æC æKY portClosedErr æFc Errors.h æT æD portClosedErr = -916, /* port was closed */ æC æKY sessClosedErr æFc Errors.h æT æD sessClosedErr = -917, /* session was closed */ æC æKY badPortNameErr æFc Errors.h æT æD badPortNameErr = -919, /* PPCPortRec malformed */ æC æKY noDefaultUserErr æFc Errors.h æT æD noDefaultUserErr = -922, /* user hasn't typed in owners name in Network Setup Control Pannel */ æC æKY notLoggedInErr æFc Errors.h æT æD notLoggedInErr = -923, /* The default userRefNum does not yet exist */ æC æKY noUserRefErr æFc Errors.h æT æD noUserRefErr = -924, /* unable to create a new userRefNum */ æC æKY networkErr æFc Errors.h æT æD networkErr = -925, /* An error has occured in the network, not too likely */ æC æKY noInformErr æFc Errors.h æT æD noInformErr = -926, /* PPCStart failed because destination did not have inform pending */ æC æKY authFailErr æFc Errors.h æT æD authFailErr = -927, /* unable to authenticate user at destination */ æC æKY noUserRecErr æFc Errors.h æT æD noUserRecErr = -928, /* Invalid user reference number */ æC æKY badServiceMethodErr æFc Errors.h æT æD badServiceMethodErr = -930, /* illegal service type, or not supported */ æC æKY badLocNameErr æFc Errors.h æT æD badLocNameErr = -931, /* location name malformed */ æC æKY guestNotAllowedErr æFc Errors.h æT æD guestNotAllowedErr = -932, /* destination port requires authentication */ æC æKY swOverrunErr æFc Errors.h æT æD swOverrunErr = 1, /*serial driver error masks*/ æC æKY parityErr æFc Errors.h æT æD parityErr = 16, /*serial driver error masks*/ æC æKY hwOverrunErr æFc Errors.h æT æD hwOverrunErr = 32, /*serial driver error masks*/ æC æKY framingErr æFc Errors.h æT æD framingErr = 64, /*serial driver error masks*/ æC æKY dsBusError æFc Errors.h æT æD dsBusError = 1, /*bus error */ æC æKY dsAddressErr æFc Errors.h æT æD dsAddressErr = 2, /*address error*/ æC æKY dsIllInstErr æFc Errors.h æT æD dsIllInstErr = 3, /*illegal instruction error*/ æC æKY dsZeroDivErr æFc Errors.h æT æD dsZeroDivErr = 4, /*zero divide error*/ æC æKY dsChkErr æFc Errors.h æT æD dsChkErr = 5, /*check trap error*/ æC æKY dsOvflowErr æFc Errors.h æT æD dsOvflowErr = 6, /*overflow trap error*/ æC æKY dsPrivErr æFc Errors.h æT æD dsPrivErr = 7, /*privilege violation error*/ æC æKY dsTraceErr æFc Errors.h æT æD dsTraceErr = 8, /*trace mode error*/ æC æKY dsLineAErr æFc Errors.h æT æD dsLineAErr = 9, /*line 1010 trap error*/ æC æKY dsLineFErr æFc Errors.h æT æD dsLineFErr = 10, /*line 1111 trap error*/ æC æKY dsMiscErr æFc Errors.h æT æD dsMiscErr = 11, /*miscellaneous hardware exception error*/ æC æKY dsCoreErr æFc Errors.h æT æD dsCoreErr = 12, /*unimplemented core routine error*/ æC æKY dsIrqErr æFc Errors.h æT æD dsIrqErr = 13, /*uninstalled interrupt error*/ æC æKY dsIOCoreErr æFc Errors.h æT æD dsIOCoreErr = 14, /*IO Core Error*/ æC æKY dsLoadErr æFc Errors.h æT æD dsLoadErr = 15, /*Segment Loader Error*/ æC æKY dsFPErr æFc Errors.h æT æD dsFPErr = 16, /*Floating point error*/ æC æKY dsNoPackErr æFc Errors.h æT æD dsNoPackErr = 17, /*package 0 not present*/ æC æKY dsNoPk1 æFc Errors.h æT æD dsNoPk1 = 18, /*package 1 not present*/ æC æKY dsNoPk2 æFc Errors.h æT æD dsNoPk2 = 19, /*package 2 not present*/ æC æKY dsNoPk3 æFc Errors.h æT æD dsNoPk3 = 20, /*package 3 not present*/ æC æKY dsNoPk4 æFc Errors.h æT æD dsNoPk4 = 21, /*package 4 not present*/ æC æKY dsNoPk5 æFc Errors.h æT æD dsNoPk5 = 22, /*package 5 not present*/ æC æKY dsNoPk6 æFc Errors.h æT æD dsNoPk6 = 23, /*package 6 not present*/ æC æKY dsNoPk7 æFc Errors.h æT æD dsNoPk7 = 24, /*package 7 not present*/ æC æKY dsMemFullErr æFc Errors.h æT æD dsMemFullErr = 25, /*out of memory!*/ æC æKY dsBadLaunch æFc Errors.h æT æD dsBadLaunch = 26, /*can't launch file*/ æC æKY dsFSErr æFc Errors.h æT æD dsFSErr = 27, /*file system map has been trashed*/ æC æKY dsStknHeap æFc Errors.h æT æD dsStknHeap = 28, /*stack has moved into application heap*/ æC æKY negZcbFreeErr æFc Errors.h æT æD negZcbFreeErr = 33, /*ZcbFree has gone negative*/ æC æKY dsFinderErr æFc Errors.h æT æD dsFinderErr = 41, /*can't load the Finder error*/ æC æKY dsBadSlotInt æFc Errors.h æT æD dsBadSlotInt = 51, /*unserviceable slot interrupt*/ æC æKY dsBadSANEOpcode æFc Errors.h æT æD dsBadSANEOpcode = 81, /*bad opcode given to SANE Pack4*/ æC æKY dsBadPatchHeader æFc Errors.h æT æD dsBadPatchHeader = 83, /*SetTrapAddress saw the “come-from” header*/ æC æKY menuPrgErr æFc Errors.h æT æD menuPrgErr = 84, /*happens when a menu is purged*/ æC æKY dsMBarNFnd æFc Errors.h æT æD dsMBarNFnd = 85, /*Menu Manager Errors*/ æC æKY dsHMenuFindErr æFc Errors.h æT æD dsHMenuFindErr = 86, /*Menu Manager Errors*/ æC æKY dsWDEFNotFound æFc Errors.h æT æD dsWDEFNotFound = 87, /*could not load WDEF*/ æC æKY dsCDEFNotFound æFc Errors.h æT æD dsCDEFNotFound = 88, /*could not load CDEF*/ æC æKY dsMDEFNotFound æFc Errors.h æT æD dsMDEFNotFound = 89, /*could not load MDEF*/ æC æKY dsNoFPU æFc Errors.h æT æD dsNoFPU = 90, /*an FPU instruction was executed and the machine doesn’t have one*/ æC æKY dsNoPatch æFc Errors.h æT æD dsNoPatch = 98, /*Can't patch for particular Model Mac*/ æC æKY dsBadPatch æFc Errors.h æT æD dsBadPatch = 99, /*Can't load patch resource*/ æC æKY dsParityErr æFc Errors.h æT æD dsParityErr = 101, /*memory parity error*/ æC æKY dsOldSystem æFc Errors.h æT æD dsOldSystem = 102, /*System is too old for this ROM*/ æC æKY ds32BitMode æFc Errors.h æT æD ds32BitMode = 103, /*booting in 32-bit on a 24-bit sys*/ æC æKY dsNeedToWriteBootBlocks æFc Errors.h æT æD dsNeedToWriteBootBlocks = 104, /*need to write new boot blocks*/ æC æKY dsNotEnoughRAMToBoot æFc Errors.h æT æD dsNotEnoughRAMToBoot = 105, /*must have at least 1.5MB of RAM to boot 7.0*/ æC æKY dsBufPtrTooLow æFc Errors.h æT æD dsBufPtrTooLow = 106, /*bufPtr moved too far during boot*/ æC æKY dsReinsert æFc Errors.h æT æD dsReinsert = 30, /*request user to reinsert off-line volume*/ æC æKY shutDownAlert æFc Errors.h æT æD shutDownAlert = 42, /*handled like a shutdown error*/ æC æKY dsShutDownOrRestart æFc Errors.h æT æD dsShutDownOrRestart = 20000, /*user choice between ShutDown and Restart*/ æC æKY dsSwitchOffOrRestart æFc Errors.h æT æD dsSwitchOffOrRestart = 20001, /*user choice between switching off and Restart*/ æC æKY dsForcedQuit æFc Errors.h æT æD dsForcedQuit = 20002, /*allow the user to ExitToShell, return if Cancel*/ æC æKY dsMacsBugInstalled æFc Errors.h æT æD dsMacsBugInstalled = -10, /*say “MacsBug Installed”*/ æC æKY dsDisassemblerInstalled æFc Errors.h æT æD dsDisassemblerInstalled = -11, /*say “Disassembler Installed”*/ æC æKY dsExtensionsDisabled æFc Errors.h æT æD dsExtensionsDisabled = -13, /*say “Extensions Disabled”*/ æC æKY dsGreeting æFc Errors.h æT æD dsGreeting = 40, /*welcome to Macintosh greeting*/ æC æKY dsSysErr æFc Errors.h æT æD dsSysErr = 32767, /*general system error*/ æC æKY WDEFNFnd æFc Errors.h æT æD WDEFNFnd = dsWDEFNotFound, æC æKY CDEFNFnd æFc Errors.h æT æD CDEFNFnd = dsCDEFNotFound, æC æKY dsNotThe1 æFc Errors.h æT æD dsNotThe1 = 31, /*not the disk I wanted*/ æC æKY dsBadStartupDisk æFc Errors.h æT æD dsBadStartupDisk = 42, /*unable to mount boot volume (sad Mac only)*/ æC æKY dsSystemFileErr æFc Errors.h æT æD dsSystemFileErr = 43, /*can’t find System file to open (sad Mac only)*/ æC æKY dsHD20Installed æFc Errors.h æT æD dsHD20Installed = -12, /*say “HD20 Startup”*/ æC æKY mBarNFnd æFc Errors.h æT æD mBarNFnd = -126, /*system error code for MBDF not found*/ æC æKY hMenuFindErr æFc Errors.h æT æD hMenuFindErr = -127, /*could not find HMenu's parent in MenuKey*/ æC æKY userBreak æFc Errors.h æT æD userBreak = -490, /*user debugger break*/ æC æKY strUserBreak æFc Errors.h æT æD strUserBreak = -491, /*user debugger break; display string on stack*/ æC æKY exUserBreak æFc Errors.h æT æD exUserBreak = -492, /*user debugger break; execute debugger commands on stack*/ æC æKY selectorErr æFc Errors.h æT æD selectorErr = paramErr, /* bad selector, for selector-based traps */ æC æKY MacOSErr æFc Errors.h æT typedef æD extern short MacOSErr; æC æKY SysError æFc Errors.h æT Function æD pascal void SysError(short errorCode) = {0x301F,0xA9C9}; æDT SysError((short) errorCode); æMM æRI II-362, V-572 æC _____________________________________________________________________________________ Trap macro _SysError On entry D0: errorCode (word) On exit All registers changed _____________________________________________________________________________________ SysError generates a system error with the ID specified by the errorCode parameter. It takes the following precise steps: 1. It saves all registers and the stack pointer. 2. It stores the system error ID in a global variable (named DSErrCode). 3. It checks to see whether there's a system error alert table in memory (by testing whether the global variable DSAlertTab is 0); if there isn't, it draws the "sad Macintosh" icon. 4. It allocates memory for QuickDraw globals on the stack, initializes QuickDraw, and initializes a grafPort in which the alert box will be drawn. 5. It checks the system error ID. If the system error ID is negative, the alert box isn't redrawn (this is used for system startup alerts, which can display a sequence of consecutive messages in the same box). If the system error ID doesn't correspond to an entry in the system error alert table, the default alert definition at the start of the table will be used, displaying the message "Sorry, a system error occurred". 6. It draws an alert box (in the rectangle specified by the global variable DSAlertRect). 7. If the text definition IDs in the alert definition for this alert aren't 0, it draws both strings. 8. If the icon definition ID in the alert definition isn't 0, it draws the icon. 9. If the procedure definition ID in the alert definition isn't 0, it invokes the procedure with the specified ID. 10. If the button definition ID in the alert definition is 0, it returns control to the procedure that called it (this is used during the disk-switch alert to return control to the File Manager after the "Please insert the disk:" message has been displayed). 11. If there's a resume procedure, it increments the button definition ID by 1. 12. It draws the buttons. 13. It hit-tests the buttons and calls the corresponding procedure code when a button is pressed. If there's no procedure code, it returns to the procedure that called it. User Alerts _____________ ID Explanation 1 Bus error: Invalid memory reference; happens only on a Macintosh XL 2 Address error: Word or long-word reference made to an odd address 3 Illegal instruction: The MC68000 received an instruction it didn't recognize. 4 Zero divide: Signed Divide (DIVS) or Unsigned Divide (DIVU) instruction with a divisor of 0 was executed. 5 Check exception: Check Register Against Bounds (CHK) instruction was executed and failed. Pascal "value out of range" errors are usually reported in this way. 6 TrapV exception: Trap On Overflow (TRAPV) instruction was executed and failed. 7 Privilege violation: Macintosh always runs in supervisor mode; perhaps an erroneous Return From Execution (RTE) instruction was executed. 8 Trace exception: The trace bit in the status register is set. 9 Line 1010 exception: The 1010 trap dispatcher has failed. 10 Line 1111 exception: Unimplemented instruction 11 Miscellaneous exception: All other MC68000 exceptions 12 Unimplemented core routine: An unimplemented trap number was encountered. 13 Spurious interrupt: The interrupt vector table entry for a particular level of interrupt is NIL; usually occurs with level 4, 5, 6, or 7 interrupts. 14 I/O system error: The File Manager is attempting to dequeue an entry from an I/O request queue that has a bad queue type field; perhaps the queue entry is unlocked. Or, the dCtlQHead field was NIL during a Fetch or Stash call. Or, a needed device control entry has been purged. 15 Segment Loader error: A GetResource call to read a segment into memory failed. 16 Floating point error: The halt bit in the floating-point environment word was set. 17-24 Can't load package: A GetResource call to read a package into memory failed. 25 Can't allocate requested memory block in the heap 26 Segment Loader error: A GetResource call to read 'CODE' resource 0 into memory failed; usually indicates a nonexecutable file. 27 File map destroyed: A logical block number was found that's greater than the number of the last logical block on the volume or less than the logical block number of the first allocation block on the volume. 28 Stack overflow error: The stack has expanded into the heap. 30 "Please insert the disk:" File Manager alert 41 The file named "Finder" can't be found on the disk. 100 Can't mount system startup volume. The system couldn't read the system resource file into memory. 32767 "Sorry, a system error occurred": Default alert message æKY Events.h æKL Button EventAvail GetCaretTime GetDblTime GetKeys GetMouse GetNextEvent StillDown TickCount WaitMouseUp WaitNextEvent activateEvt activeFlag activMask adbAddrMask alphaLock app1Evt app1Mask app2Evt app2Mask app3Evt app3Mask app4Evt app4Mask autoKey autoKeyMask btnState charCodeMask cmdKey controlKey convertClipboardFlag diskEvt diskMask driverEvt driverMask EventRecord everyEvent highLevelEventMask keyCodeMask keyDown keyDownMask KeyMap keyUp keyUpMask mDownMask mouseDown mouseMovedMessage mouseUp mUpMask networkEvt networkMask nullEvent optionKey osEvt osEvtMessageMask osMask resumeFlag shiftKey suspendResumeMessage updateEvt updateMask æKY nullEvent æFc Events.h æT æD nullEvent = 0, æC »Event Code The what field of an event record contains an event code identifying the type of the event. The event codes are available as predefined constants: #define nullEvent 0 /*null*/ #define mouseDown 1 /*mouse-down*/ #define mouseUp 2 /*mouse-up*/ #define keyDown 4 /*key-down*/ #define keyUp 3 /*key-up*/ #define autoKey 5 /*auto-key*/ #define updateEvt 6 /*update*/ #define diskEvt 7 /*disk-inserted*/ #define activateEvt 8 /*activate*/ #define networkEvt 10 /*network*/ #define driverEvt 11 /*device driver*/ #define app1Evt 12 /*application-defined*/ #define app2Evt 13 /*application-defined*/ #define app3Evt 14 /*application-defined*/ #define app4Evt 15 /*application-defined*/ æKY mouseDown æFc Events.h æT æD mouseDown = 1, æC æKY mouseUp æFc Events.h æT æD mouseUp = 2, æC æKY keyDown æFc Events.h æT æD keyDown = 3, æC æKY keyUp æFc Events.h æT æD keyUp = 4, æC æKY autoKey æFc Events.h æT æD autoKey = 5, æC æKY updateEvt æFc Events.h æT æD updateEvt = 6, æC æKY diskEvt æFc Events.h æT æD diskEvt = 7, æC æKY activateEvt æFc Events.h æT æD activateEvt = 8, æC æKY osEvt æFc Events.h æT æD osEvt = 15, æC æKY mDownMask æFc Events.h æT æD mDownMask = 2, æC _______________________________________________________________________________ »EVENT MASKS _______________________________________________________________________________ Some of the Event Manager routines can be restricted to operate on a specific event type or group of types; in other words, the specified event types are enabled while all others are disabled. For instance, instead of just requesting the next available event, you can specifically ask for the next keyboard event. You specify which event types a particular Event Manager call applies to by supplying an event mask as a parameter. This is an integer in which there’s one bit position for each event type, as shown in Figure 8. The bit position representing a given type corresponds to the event code for that type—for example, update events (event code 6) are specified by bit 6 of the mask. A 1 in bit 6 means that this Event Manager call applies to update events; a 0 means that it doesn’t. •••Refer to Figure 8.••• Figure 8–Event Mask Masks for each individual event type are available as predefined constants: #define mDownMask 2 /*mouse-down*/ #define mUpMask 4 /*mouse-up*/ #define keyDownMask 8 /*key-down*/ #define keyUpMask 16 /*key-up*/ #define autoKeyMask 32 /*auto-key*/ #define updateMask 64 /*update*/ #define diskMask 128 /*disk-inserted*/ #define activMask 256 /*activate*/ #define networkMask 1024 /*network*/ #define driverMask 2048 /*device driver*/ #define app1Mask 4096 /*application-defined*/ #define app2Mask 8192 /*application-defined*/ #define app3Mask 16384 /*application-defined*/ #define app4Mask -32768 /*application-defined*/ Note: Null events can’t be disabled; a null event will always be reported when none of the enabled types of events are available. The following predefined mask designates all event types: CONST everyEvent = -1; {all event types} You can form any mask you need by adding or subtracting these mask constants. For example, to specify every keyboard event, use keyDownMask + keyUpMask + autoKeyMask For every event except an update, use everyEvent - updateMask Note: It’s recommended that you always use the event mask everyEvent unless there’s a specific reason not to. There’s also a global system event mask that controls which event types get posted into the event queue. Only event types corresponding to bits set in the system event mask are posted; all others are ignored. When the system starts up, the system event mask is set to post all except key-up event—that is, it’s initialized to everyEvent - keyUpMask Note: Key-up events are meaningless for most applications. Your application will usually want to ignore them; if not, it can set the system event mask with the Operating System Event Manager procedure SetEventMask. æKY mUpMask æFc Events.h æT æD mUpMask = 4, æC æKY keyDownMask æFc Events.h æT æD keyDownMask = 8, æC æKY keyUpMask æFc Events.h æT æD keyUpMask = 16, æC æKY autoKeyMask æFc Events.h æT æD autoKeyMask = 32, æC æKY updateMask æFc Events.h æT æD updateMask = 64, æC æKY diskMask æFc Events.h æT æD diskMask = 128, æC æKY activMask æFc Events.h æT æD activMask = 256, æC æKY highLevelEventMask æFc Events.h æT æD highLevelEventMask = 1024, æC æKY osMask æFc Events.h æT æD osMask = -32768, æC æKY everyEvent æFc Events.h æT æD everyEvent = -1, æC æKY charCodeMask æFc Events.h æT æD charCodeMask = 0x000000FF, æC æKY keyCodeMask æFc Events.h æT æD keyCodeMask = 0x0000FF00, æC æKY adbAddrMask æFc Events.h æT æD adbAddrMask = 0x00FF0000, æC æKY osEvtMessageMask æFc Events.h æT æD osEvtMessageMask = 0xFF000000, æC æKY mouseMovedMessage æFc Events.h æT æD mouseMovedMessage = 0xFA, æC æKY suspendResumeMessage æFc Events.h æT æD suspendResumeMessage = 0x01, æC æKY resumeFlag æFc Events.h æT æD resumeFlag = 1, /* bit 0 of message indicates resume vs suspend */ æC æKY convertClipboardFlag æFc Events.h æT æD convertClipboardFlag = 2, /* bit 1 in resume message indicates clipboard change */ æC æKY activeFlag æFc Events.h æT æD activeFlag = 1, /*bit 0 of modifiers for activate event*/ æC »Modifier Flags As mentioned above, the modifiers field of an event record contains further information about activate events and the state of the modifier keys and mouse button at the time the event was posted (see Figure 7). You might look at this field to find out, for instance, whether the Command key was down when a mouse-down event was posted (which in many applications affects the way objects are selected) or when a key-down event was posted (which could mean the user is choosing a menu item by typing its keyboard equivalent). •••Refer to Figure 7.••• Figure 7–Modifier Flags The following predefined constants are useful as masks for reading the flags in the modifiers field: #define activeFlag 1 /*set if window being activated*/ #define btnState 128 /*set if mouse button up*/ #define cmdKey 256 /*set if Command key down*/ #define shiftKey 512 /*set if Shift key down*/ #define alphaLock 1024 /*set if Caps Lock key down*/ #define optionKey 2048 /*set if Option key down*/ #define controlKey 4096 /*set if Control key down*/ The activeFlag bit gives further information about activate events; it’s set if the window pointed to by the event message is being activated, or 0 if the window is being deactivated. The remaining bits indicate the state of the mouse button and modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas the bits for the four modifier keys are set if their corresponding keys are down. æKY btnState æFc Events.h æT æD btnState = 128, /*Bit 7 of low byte is mouse button state*/ æC æKY cmdKey æFc Events.h æT æD cmdKey = 256, /*Bit 0*/ æC æKY shiftKey æFc Events.h æT æD shiftKey = 512, /*Bit 1*/ æC æKY alphaLock æFc Events.h æT æD alphaLock = 1024, /*Bit 2 */ æC æKY optionKey æFc Events.h æT æD optionKey = 2048, /*Bit 3 of high byte*/ æC æKY controlKey æFc Events.h æT æD controlKey = 4096, æC æKY networkEvt æFc Events.h æT æD networkEvt = 10, æC æKY driverEvt æFc Events.h æT æD driverEvt = 11, æC æKY app1Evt æFc Events.h æT æD app1Evt = 12, æC æKY app2Evt æFc Events.h æT æD app2Evt = 13, æC æKY app3Evt æFc Events.h æT æD app3Evt = 14, æC æKY app4Evt æFc Events.h æT æD app4Evt = 15, æC æKY networkMask æFc Events.h æT æD networkMask = 1024, æC æKY driverMask æFc Events.h æT æD driverMask = 2048, æC æKY app1Mask æFc Events.h æT æD app1Mask = 4096, æC æKY app2Mask æFc Events.h æT æD app2Mask = 8192, æC æKY app3Mask æFc Events.h æT æD app3Mask = 16384, æC æKY app4Mask æFc Events.h æT æD app4Mask = -32768, æC æKY EventRecord æFc Events.h æT struct æD struct EventRecord { short what; long message; long when; Point where; short modifiers; }; typedef struct EventRecord EventRecord; æC _______________________________________________________________________________ »EVENT RECORDS _______________________________________________________________________________ Every event is represented internally by an event record containing all pertinent information about that event. The event record includes the following information: • the type of event • the time the event was posted (in ticks since system startup) • the location of the mouse at the time the event was posted (in global coordinates) • the state of the mouse button and modifier keys at the time the event was posted • any additional information required for a particular type of event, such as which key the user pressed or which window is being activated Every event has an event record containing this information—even null events. Event records are defined as follows: TYPE EventRecord = RECORD what: INTEGER; {event code} message: LONGINT; {event message} when: LONGINT; {ticks since startup} where: Point; {mouse location} modifiers: INTEGER {modifier flags} END; The when field contains the number of ticks since the system last started up, and the where field gives the location of the mouse, in global coordinates, at the time the event was posted. The other three fields are described below. _______________________________________________________________________________ »Event Code The what field of an event record contains an event code identifying the type of the event. The event codes are available as predefined constants: CONST nullEvent = 0; {null} mouseDown = 1; {mouse-down} mouseUp = 2; {mouse-up} keyDown = 3; {key-down} keyUp = 4; {key-up} autoKey = 5; {auto-key} updateEvt = 6; {update} diskEvt = 7; {disk-inserted} activateEvt = 8; {activate} networkEvt = 10; {network} driverEvt = 11; {device driver} app1Evt = 12; {application-defined} app2Evt = 13; {application-defined} app3Evt = 14; {application-defined} app4Evt = 15; {application-defined} _______________________________________________________________________________ »Event Message The message field of an event record contains the event message, which conveys additional important information about the event. The nature of this information depends on the event type, as summarized in the following table and described below. Event type Event message Keyboard Character code, key code, and ADB address field Activate, update Pointer to window Disk-inserted Drive number in low-order word, File Manager result code in high-order word Mouse-down, Undefined mouse-up, null Network Handle to parameter block Device driver See chapter describing driver Application-defined Whatever you wish For keyboard events, the low-order byte of the low-order word of the event message contains the ASCII character code generated by the key or combination of keys that was pressed or released; usually this is all you’ll need. However, as described in the Apple Desktop Bus chapter, the Macintosh II and SE can be connected to multiple keyboards. To identify the origin of keyboard events, the keyboard event message contains a new ADB address field. It now has the structure shown in Figure 2. Warning: The high byte of the event message for keyboard events is reserved for future use, and is not presently guaranteed to be zero. The event message for non-keyboard events remains the same as described above. •••Refer to Figure 2.••• Figure 2–Event Message for Keyboard Events The key code in the event message for a keyboard event represents the character key that was pressed or released; this value is always the same for any given character key, regardless of the modifier keys pressed along with it. Key codes are useful in special cases—in a music generator, for example—where you want to treat the keyboard as a set of keys unrelated to characters. Figure 3 gives the key codes for all the keys on the keyboard and keypad. (Key codes are shown for modifier keys here because they’re meaningful in other contexts, as explained later.) Both the U.S. and international keyboards are shown; in some cases the codes are quite different (for example, space and Enter are reversed). Three keyboards are now available as standard equipment with Macintosh computers sold in the U.S. They are • The Macintosh Plus Keyboard, which includes cursor control keys and an integral keypad. Its layout and key coding is shown in Figure 4. • The Macintosh II Keyboard, also shipped with the Macintosh SE, which adds Esc (Escape) and Control keys and is connected to the Apple Desktop Bus. Its layout and key coding is shown in Figure 5. • The Apple Extended Keyboard, which the user may connect to the Apple Desktop Bus of any Macintosh II or Macintosh SE computer. Its layout and key coding is shown in Figure 6. These figures show the virtual key codes for each key; they are the key codes that actually appear in keyboard events. In the case of the Macintosh II and Apple Extended Keyboards, however, the hardware produces raw key codes, which may be different. Raw key codes are translated to virtual key codes by the 'KMAP' resource in the System Folder. By modifying the 'KMAP' resource you can change the key codes for any keys. Similarly, you can change the ASCII codes corresponding to specific key codes by modifying the 'KCHR' resource in the System Folder. The 'KMAP' and 'KCHR' resources are described in the Resource Manager chapter. With both the Macintosh II and the Apple Extended keyboards, the standard 'KMAP' resource supplied in the system folder reassigns the following raw key codes to different virtual key codes: Key Raw key code Virtual key code Control 36 3B Left cursor 3B 7B Right cursor 3C 7C Down cursor 3D 7D Up cursor 3E 7E The standard 'KMAP' resource leaves all other raw key codes and virtual key codes the same. With the Apple Extended Keyboard, the virtual key codes for three more keys may be easily reassigned, as described above under “Reassigning Right Key Codes”. The following predefined constants are available to help you access the character code and key code: CONST charCodeMask = $000000FF; {character code} keyCodeMask = $0000FF00; {key code} •••Refer to Figure 3.••• Figure 3–Key Codes •••Refer to Figure 4.••• Figure 4–Macintosh Plus Keyboard •••Refer to Figure 5.••• Figure 5–Macintosh II Keyboard •••Refer to Figure 6.••• Figure 6–Apple Extended Keyboard Note: You can use the Toolbox Utility function BitAnd with these constants; for instance, to access the character code, use charCode := BitAnd(my Event.message,charCodeMask) _______________________________________________________________________________ THE TOOLBOX EVENT MANAGER _______________________________________________________________________________ For activate and update events, the event message is a pointer to the window affected. (If the event is an activate event, additional important information about the event can be found in the modifiers field of the event record, as described below.) For disk-inserted events, the low-order word of the event message contains the drive number of the disk drive into which the disk was inserted: 1 for the Macintosh’s built-in drive, and 2 for the external drive, if any. Numbers greater than 2 denote additional disk drives connected to the Macintosh. By the time your application receives a disk-inserted event, the system will already have attempted to mount the volume on the disk by calling the File Manager function MountVol; the high-order word of the event message will contain the result code returned by MountVol. For mouse-down, mouse-up, and null events, the event message is undefined and should be ignored. The event message for a network event contains a handle to a parameter block, as described in the AppleTalk Manager chapter. For device driver events, the contents of the event message depend on the situation under which the event was generated; the chapters describing those situations will give the details. Finally, you can use the event message however you wish for application-defined event types. _______________________________________________________________________________ »Modifier Flags As mentioned above, the modifiers field of an event record contains further information about activate events and the state of the modifier keys and mouse button at the time the event was posted (see Figure 7). You might look at this field to find out, for instance, whether the Command key was down when a mouse-down event was posted (which in many applications affects the way objects are selected) or when a key-down event was posted (which could mean the user is choosing a menu item by typing its keyboard equivalent). •••Refer to Figure 7.••• Figure 7–Modifier Flags The following predefined constants are useful as masks for reading the flags in the modifiers field: CONST activeFlag = 1; {set if window being activated} btnState = 128; {set if mouse button up} cmdKey = 256; {set if Command key down} shiftKey = 512; {set if Shift key down} alphaLock = 1024; {set if Caps Lock key down} optionKey = 2048; {set if Option key down} ControlKey = 4096; {set if Control key down} The activeFlag bit gives further information about activate events; it’s set if the window pointed to by the event message is being activated, or 0 if the window is being deactivated. The remaining bits indicate the state of the mouse button and modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas the bits for the four modifier keys are set if their corresponding keys are down. æKY KeyMap æFc Events.h æT typedef æD typedef long KeyMap[4]; æC æKY GetNextEvent æFc Events.h æT Function æTN A970 æD pascal Boolean GetNextEvent(short eventMask,EventRecord *theEvent) = 0xA970; æDT Boolean myVariable = GetNextEvent((short) eventMask,(EventRecord *) theEvent); æMM æRT 3, 5, 85, 194, 205 æRI I-257, N3-1, N5-1, N85, P-30, 32, 34, 39, 40, 97, 108, 173 æC GetNextEvent returns the next available event of a specified type or types and, if the event is in the event queue, removes it from the queue. The event is returned in the parameter theEvent. The eventMask parameter specifies which event types are of interest. GetNextEvent returns the next available event of any type designated by the mask, subject to the priority rules discussed above under “Priority of Events”. If no event of any of the designated types is available, GetNextEvent returns a null event. Note: Events in the queue that aren’t designated in the mask are kept in the queue; if you want to remove them, you can do so by calling the Operating System Event Manager procedure FlushEvents. Before reporting an event to your application, GetNextEvent first calls the Desk Manager function SystemEvent to see whether the system wants to intercept and respond to the event. If so, or if the event being reported is a null event, GetNextEvent returns a function result of FALSE; a function result of TRUE means that your application should handle the event itself. The Desk Manager intercepts the following events: • activate and update events directed to a desk accessory • mouse-up and keyboard events, if the currently active window belongs to a desk accessory Note: In each case, the event is intercepted by the Desk Manager only if the desk accessory can handle that type of event; however, as a rule all desk accessories should be set up to handle activate, update, and keyboard events and should not handle mouse-up events. The Desk Manager also intercepts disk-inserted events: It attempts to mount the volume on the disk by calling the File Manager function MountVol. GetNextEvent will always return TRUE in this case, though, so that your application can take any further appropriate action after examining the result code returned by MountVol in the event message. (See the Desk Manager and File Manager chapters.) GetNextEvent returns TRUE for all other non-null events (including all mouse-down events, regardless of which window is active), leaving them for your application to handle. GetNextEvent also makes the following processing happen, invisible to your program: • If the “alarm” is set and the current time is the alarm time, the alarm goes off (a beep followed by blinking the apple symbol in the menu bar). The user can set the alarm with the Alarm Clock desk accessory. • If the user holds down the Command and Shift keys while pressing a numeric key that has a special effect, that effect occurs. The standard such keys are 1 and 2 for ejecting the disk in the internal or external drive, and 3 and 4 for writing a snapshot of the screen to a MacPaint document or to the printer. Note: Advanced programmers can implement their own code to be executed in response to Command-Shift-number combinations (except for Command- Shift-1 and 2, which can’t be changed). The code corresponding to a particular number must be a routine having no parameters, stored in a resource whose type is 'FKEY' and whose ID is the number. The system resource file contains code for the numbers 3 and 4. Assembly-language note: You can disable GetNextEvent’s processing of Command- Shift-number combinations by setting the global variable ScrDmpEnb (a byte) to 0. æKY WaitNextEvent æFc Events.h æT Function æTN A860 æD pascal Boolean WaitNextEvent(short eventMask,EventRecord *theEvent,unsigned long sleep, RgnHandle mouseRgn) = 0xA860; æDT Boolean myVariable = WaitNextEvent((short) eventMask,(EventRecord *) theEvent,(unsigned long) sleep,() RgnHandle mouseRgn); æRT 158, 177, 180, 194, 205 æRI N158-1 æC æKY EventAvail æFc Events.h æT Function æTN A971 æD pascal Boolean EventAvail(short eventMask,EventRecord *theEvent) = 0xA971; æDT Boolean myVariable = EventAvail((short) eventMask,(EventRecord *) theEvent); æMM æRT 194 æRI I-259 æC EventAvail works exactly the same as GetNextEvent except that if the event is in the event queue, it’s left there. Note: An event returned by EventAvail will not be accessible later if in the meantime the queue becomes full and the event is discarded from it; since the events discarded are always the oldest ones in the queue, however, this will happen only in an unusually busy environment. æKY GetMouse æFc Events.h æT Function æTN A972 æD pascal void GetMouse(Point *mouseLoc) = 0xA972; æDT GetMouse((Point *) mouseLoc); æMM æRI I-259 æC GetMouse returns the current mouse location in the mouseLoc parameter. The location is given in the local coordinate system of the current grafPort (which might be, for example, the currently active window). Notice that this differs from the mouse location stored in the where field of an event record; that location is always in global coordinates. æKY Button æFc Events.h æT Function æTN A974 æD pascal Boolean Button(void) = 0xA974; æDT Boolean myVariable = Button()(void); æMM æRI I-259 æC The Button function returns TRUE if the mouse button is currently down, and FALSE if it isn’t. æKY StillDown æFc Events.h æT Function æTN A973 æD pascal Boolean StillDown(void) = 0xA973; æDT Boolean myVariable = StillDown()(void); æMM æRT 194 æRI I-259 æC Usually called after a mouse-down event, StillDown tests whether the mouse button is still down. It returns TRUE if the button is currently down and there are no more mouse events pending in the event queue. This is a true test of whether the button is still down from the original press—unlike Button (above), which returns TRUE whenever the button is currently down, even if it has been released and pressed again since the original mouse-down event. æKY WaitMouseUp æFc Events.h æT Function æTN A977 æD pascal Boolean WaitMouseUp(void) = 0xA977; æDT Boolean myVariable = WaitMouseUp()(void); æMM æRT 194 æRI I-259 æC WaitMouseUp works exactly the same as StillDown (above), except that if the button is not still down from the original press, WaitMouseUp removes the preceding mouse-up event before returning FALSE. If, for instance, your application attaches some special significance both to mouse double-clicks and to mouse-up events, this function would allow your application to recognize a double-click without being confused by the intervening mouse-up. æKY GetKeys æFc Events.h æT Function æTN A976 æD pascal void GetKeys(KeyMap theKeys) = 0xA976; æDT GetKeys((KeyMap) theKeys); æMM æRI I-259 æC GetKeys reads the current state of the keyboard (and keypad, if any) and returns it in the form of a keyMap: TYPE KeyMap = PACKED ARRAY[0..127] OF BOOLEAN; Each key on the keyboard or keypad corresponds to an element in the keyMap. The index into the keyMap for a particular key is the same as the key code for that key. (The key codes are shown in Figure 3 above.) The keyMap element is TRUE if the corresponding key is down and FALSE if it isn’t. The maximum number of keys that can be down simultaneously is two character keys plus any combination of the four modifier keys. æKY TickCount æFc Events.h æT Function æTN A975 æD pascal unsigned long TickCount(void) = 0xA975; æDT unsigned long myVariable = TickCount()(void); æMM æRI I-260 æC TickCount returns the current number of ticks (sixtieths of a second) since the system last started up. Warning: Don’t rely on the tick count being exact; it will usually be accurate to within one tick, but may be off by more than that. The tick count is incremented during the vertical retrace interrupt, but it’s possible for this interrupt to be disabled. Furthermore, don’t rely on the tick count being incremented to a certain value, such as testing whether it has become equal to its old value plus 1; check instead for “greater than or equal to” (since an interrupt task may keep control for more than one tick). Assembly-language note: The value returned by this function is also contained in the global variable Ticks. æKY GetDblTime æFc Events.h æT Function æD #define GetDblTime() (* (unsigned long*) 0x02F0) æDT #define myVariable = GetDblTime(); æRI I-260 æC [Not in ROM] GetDblTime returns the suggested maximum difference (in ticks) that should exist between the times of a mouse-up event and a mouse-down event for those two mouse clicks to be considered a double-click. The user can adjust this value by means of the Control Panel desk accessory. Assembly-language note: This value is available to assembly-language programmers in the global variable DoubleTime. æKY GetCaretTime æFc Events.h æT Function æD #define GetCaretTime() (* (unsigned long*) 0x02F4) æDT #define myVariable = GetCaretTime(); æRI I-260 æC [Not in ROM] GetCaretTime returns the time (in ticks) between blinks of the “caret” (usually a vertical bar) marking the insertion point in editable text. If you aren’t using TextEdit, you’ll need to cause the caret to blink yourself; on every pass through your program’s main event loop, you should check this value against the elapsed time since the last blink of the caret. The user can adjust this value by means of the Control Panel desk accessory. Assembly-language note: This value is available to assembly-language programmers in the global variable CaretTime. æKY FCntl.h æC close faccess open unlink creat fcntl read write dup lseek F_DELETE F_OPEN O_APPEND O_RDWR F_DUPFD F_RENAME O_CREAT O_RSRC F_GFONTINFO F_SFONTINFO O_EXCL O_TRUNC F_GPRINTREC F_SPRINTREC O_RDONLY O_WRONLY F_GTABINFO F_STABINFO Low-level file I/O (non-ANSI extensions)—FCntl.h non-ANSI extensions:low-level file I/O MPW 3.0 C contains several file-control functions in addition to those required by the ANSI draft C standard. These functions, declared in the header file FCntl.h, preserve compatibility with MPW 2.0 C. Some of these functions duplicate, at a lower level, functions in the header file StdIO.h. (For example, open is a low-level equivalent of fopen.) Using the StdIO.h functions whenever possible will improve portability and robustness. æKY close æFc FCntl.h æC Synopsis #include <FCntl.h> int close(int fildes); Description The close; function closes the file descriptor indicated by fildes. Parameter fildes is a file descriptor obtained from an open, creat, dup, or fcntl call. The function close fails if fildes is not a valid open file descriptor [EBADF]. Diagnostics Upon successful completion, a value of 0 is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. See also creat, dup, fclose, fcntl, ferror, open, stdio æKY creat æFc FCntl.h æC Synopsis #include <FCntl.h> int creat(const char *filename); Description The creat; function creates a new file or prepares to rewrite an existing file, filename. If the file exists, the length of its data fork is set to 0. The function creat(filename) is equivalent to open(filename, O_WRONLY|O_TRUNC|O_CREAT) Upon successful completion, a nonnegative integer (the file descriptor) is returned and the file is open for writing. The file pointer is set to the beginning of the file. A maximum of about 30 files may be open at a given time: the actual maximum depends upon the current system environment. Return value Upon successful completion, a nonnegative integer (the file descriptor) is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. Note Other implementations of creat specify a second parameter, mode. This version ignores any second parameter. See also close, open, read, write æKY dup æFc FCntl.h æC Synopsis #include <Fcntl.h> int dup(int fildes); Description The dup; function returns a new file descriptor with these features: It refers to the same open file as the original. It uses the same file pointer as the original. It has the same access mode (that is, read, write, or read/write) as the original. The fildes parameter is a file descriptor obtained from an open, creat, dup, or fcntl call. The new file descriptor returned by dup is the lowest one available. The function call dup(fildes) is equivalent to fcntl(fildes, F_DUPFD, 0). The dup function fails if parameter fildes is not a valid open file descriptor [EBADF]. Return value Upon successful completion, a nonnegative integer (the file descriptor) is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. See also close, fcntl, ferror, open æKY F_DELETE æFc FCntl.h æD #define F_DELETE (('d'<<8)|01) æKY F_DUPFD æFc FCntl.h æD #define F_DUPFD 0 /*Duplicate fildes*/ æKY F_GFONTINFO æFc FCntl.h æD #define F_GFONTINFO (('e'<<8)|02) æKY F_GPRINTREC æFc FCntl.h æD #define F_GPRINTREC (('e'<<8)|04) æKY F_GTABINFO æFc FCntl.h æD #define F_GTABINFO (('e'<<8)|00) /*'e' => "editor" ops*/ æKY F_OPEN æFc FCntl.h æD #define F_OPEN (('d'<<8)|00) /*d' => "directory" ops*/ æKY F_RENAME æFc FCntl.h æD #define F_RENAME (('d'<<8)|02) æKY F_SFONTINFO æFc FCntl.h æD #define F_SFONTINFO (('e'<<8)|03) æKY F_SPRINTREC æFc FCntl.h æD #define F_SPRINTREC (('e'<<8)|05) æKY F_STABINFO æFc FCntl.h æD #define F_STABINFO (('e'<<8)|01) æKY faccess æFc FCntl.h æC Synopsis #include <FCntl.h> int faccess(const char *filename, unsigned int cmd, long *arg); Description The faccess; function provides access to control and status information for named files. (Compare function ioctl, which provides different control and status information for open files.) The cmd parameter must be set to one of the constants in the following list to indicate what operation is to be performed on the file. As Noted in the list, some calls to faccess also require the arg parameter, usually as a long or as a pointer to a long. The following commands are available to all programs: Value of cmd Description F_DELETE Deletes the named file, or returns an error if the file is open. Parameter arg is ignored. F_RENAME Renames the named file. Parameter arg is a pointer to a string containing the new name. The following commands can be used only by MPW tools: Value of cmd Description F_GTABINFO Gets the tab offset for the MPW text file filename. The tab offset is stored in the long integer pointed to by arg. The tab offset is expressed as an integer number of spaces. The width of the space character in the current font determines the actual distance of the tab offset. F_STABINFO Sets the tab offset for the MPW text file filename. The tab offset is specified as a long value in arg. F_GFONTINFO Gets the font number and font size for an MPW text file filename. The font number is stored in the high-order half of the long pointed to by arg; the font size is stored in the low order half of the same long. F_SFONTINFO Sets the font number and font size for the MPW text file, filename. The font number is specified in the high-order half of arg; the font size is specified in the low-order half of arg. F_GPRINTREC Gets a print record TPrint for an MPW text file, filename; arg is a handle to the print record. F_SPRINTREC Sets a print record for the MPW text file filename; arg is a handle to the print record. F_OPE Reserved for operating system use. F_GSELINFO Gets the selection information for the MPW text file filename. F_SSELINFO Sets the selection information for the MPW text file filename. F_GWININFO Gets the current window position. F_SWININFO Sets the current window position. The commands F_GTABINFO and F_GFONTINFO pass arg as a pointer to a long; F_STABINFO and F_SFONTINFO pass arg as a long value; and F_GPRINTREC and F_SPRINTREC pass arg as a handle to a print record. Return values Upon successful completion, faccess returns a nonnegative value, usually 0. If the device for the named file cannot perform the requested command, faccess returns –1 and errno is set to indicate the error. If the requested resource for F_GTABINFO, F_GFONTINFO, or F_GPRINTREC does not exist for the named file, default values are stored and the function returns a value greater than 0. Note Before faccess is called with F_GPRINTREC or F_SPRINTREC, the Printing Manager must be initialized and the print record handle THPrint must be allocated. The font size must be 9, 10, 12, 14, 18, or 24; the font number must be 0 or a positive integer. The following sequence must be used with these print command values: res = CurResFile(); PRClose(); UseResFile(res); PROpen(); /* do whatever, including call faccess print commands */ PRClose(); UseResFile(res); See also ioctl, unlink æKY fcntl æFc FCntl.h æC Synopsis #include <FCntl.h> int fcntl(int fildes, unsigned int cmd, int arg); Description The fcntl; function duplicates a file descriptor. A file remains open until all of its file descriptors are closed. The fildes parameter is an open file descriptor obtained from an open, creat, dup, or fcntl call. The cmd parameter takes the value F_DUPFD, which tells fcntl to return the lowest-numbered available file descriptor greater than or equal to arg. Normally arg is greater than or equal to 3, to avoid obtaining the standard file descriptors 0, 1, and 2. The function fcntl returns a new file descriptor that points to the same open file as fildes. The new file descriptor has the same access mode (read, write, or read/write) and file pointer as fildes. Any I/O operation changes the file pointer for all file descriptors that share it. The fcntl function fails if one or more of the following error conditions are true: Parameter fildes is not a valid open file descriptor [EBADF]. Parameter arg is negative or greater than the highest allowable file descriptor [EINVAL]. Return values Upon successful completion, the value returned is a new file descriptor. Otherwise, a value of –1 is returned and errno is set to indicate the error. Note MPW 3.0 C does not support the F_GETFD, F_SETFD, F_GETFL, and F_SETFL commands of fcntl. See also close, dup, ferror, ioctl, open æKY lseek æFc FCntl.h æC Synopsis #include <FCntl.h> #define SEEK_SET 0 #define SEEK_CUR 1 #define SEEK_END 2 long lseek(int fildes, long int offset, int whence); Description A file descriptor, fildes, is returned from a call to creat, dup, fcntl, or open. The lseek; function sets the file pointer associated with fildes, thus determining the position of the next read or write operation. The value of whence determines how the offset parameter is used, according to these rules: If whence is SEEK_SET, the new position is offset bytes from the beginning of the file. If whence is SEEK_CUR, the new position is the current location plus offset. If whence is SEEK_END, the new position is the size of the file plus offset. If whence is SEEK_SET or SEEK_CUR, the value of offset may be negative. Upon successful completion, the file-pointer value as measured in bytes from the beginning of the file is returned. The file pointer remains unchanged and lseek fails if one or more of the following error conditions are true: File descriptor fildes is not open [EBADF]. Parameter whence is not equal to SEEK_SET, SEEK_CUR, or SEEK_END [EINVAL]. The resulting file pointer would point past the end-of-file [ESPIPE]. The resulting file pointer would point before the beginning of the file [EINVAL]. Some devices are incapable of seeking. The value of the file pointer associated with such a device is undefined. Return values Upon successful completion, a nonnegative long integer indicating the file-pointer value is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. Note In previous versions of the Standard C Library, tell;(fildes) was a function that returned the current file position. It is equivalent to the call lseek(fildes, 0L, 1). Warning The lseek function has no effect on a file opened with the O_APPEND flag because the next write to the file always repositions the file pointer to the end before writing. See also ferror, fseek, open, stdio, write æKY O_APPEND æFc FCntl.h æD #define O_APPEND (1<<3) /*append (writes guaranteed at the end)*/ æKY O_CREAT æFc FCntl.h æD #define O_CREAT (1<<8) /*Open with file create*/ æKY O_EXCL æFc FCntl.h æD #define O_EXCL (1<<10) /*Exclusive open*/ æKY O_RDONLY æFc FCntl.h æD #define O_RDONLY 0 /*Bits 0 and 1 are used internally*/ æKY O_RDWR æFc FCntl.h æD #define O_RDWR 2 æKY O_RSRC æFc FCntl.h æD #define O_RSRC (1<<4) /*Open the resource fork*/ æKY O_TRUNC æFc FCntl.h æD #define O_TRUNC (1<<9) /*Open with truncation*/ æKY O_WRONLY æFc FCntl.h æD #define O_WRONLY 1 /*Values 0..2 are historical*/ æKY open æFc FCntl.h æC Synopsis #include <FCntl.h> int open(const char *filename, int oflag); Description The open; function opens a file descriptor for the named file and sets the file-status flags according to the value of oflag. The parameter filename is a disk file, window, selection, or pseudofile. (See “Pseudo-Filenames” in Chapter 5 of the Macintosh Programmer’s Workshop 3.0 Reference for more information.) The value of oflag is constructed by performing an OR operation on the flag settings, for example: fildes = open("MyFile", O_WRONLY|O_CREAT|O_TRUNC); To construct oflag, first select one of the following access modes: O_RDONLY Open for reading only. WR_ONLY Open for writing only. O_RDWR Open for reading and writing. Then optionally add one or more of these modifiers: O_APPEND The file pointer is set to the end of the file before each write. O_CREAT If the file does not exist, it is created. O_TRUNC If the file exists, its length is truncated to 0; the mode is unchanged. O_RSRC The file’s resource fork is opened. (Normally, the data fork is opened.) O_BINARY Open as a binary stream (supported but not used by the system). The following setting is valid only if O_CREAT is also specified: O_EXCL The function open fails if the file exists. Upon successful completion, a nonnegative integer (the file descriptor) is returned. The file pointer used to mark the current position within the file is set to the beginning of the file. The named file is opened unless one or more of the following error conditions is true: O_CREAT is not set and the named file does not exist [ENOENT]. More than about 30 file descriptors are currently open. The actual limit varies according to run-time conditions [EMFILE]. O_CREAT and O_EXCL are set and the named file exists [EEXIST]. Return value Upon successful completion, a nonnegative integer (the file descriptor) is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. See also close, creat, dup, fcntl, ferror, fopen, lseek, read, stdio, write æKY read æFc FCntl.h æC Synopsis #include <Fcntl.h> int read(int fildes, char* buf, unsigned long nbyte); Description The read; function transfers up to nbyte bytes from the file associated with fildes into the buffer pointed to by buf. File descriptor fildes is obtained from a call to open, creat, a, or a. On devices capable of seeking, read starts reading at the current position of the file pointer associated with fildes. Upon return from read, the file pointer is incremented by the number of bytes actually read. Nonseeking devices always read from the current position. The value of a file pointer associated with such a file is undefined. Upon successful completion, read returns the number of bytes actually read and placed in the buffer. This number may be less than nbyte if the file is associated with a window or if the number of bytes left in the file is less than nbyte bytes. A value of 0 is returned when an end-of-file has been reached, and a value of –1 is returned if a read error occurred. The function read fails if fildes is not a valid file descriptor open for reading. [EBADF] File descriptor 0 is opened by the MPW Shell as standard input. Return values Upon successful completion, a nonnegative integer is returned, indicating the number of bytes actually read. Otherwise, –1 is returned and errno is set to indicate the error. See also creat, ferror, fread, open, stdio æKY unlink æFc FCntl.h æC Synopsis #include <FCntl.h> int unlink(const char *fileName); Description The unlink; function deletes the named file. The function fails if the named file is open. This function is the UNIX (and MPW 2.0 C) equivalent of the ANSI remove function, and is included for compatibility. A call to unlink is equivalent to faccess(fileName, F_DELETE, 0) Diagnostics Upon successful completion, a value of 0 is returned. Otherwise, a value of –1 is returned and errno is set to indicate the error. See also faccess æKY write æFc FCntl.h æC Synopsis #include <Fcntl.h> int write(int fildes, const char* buf, unsigned long nbyte); Description The write; function attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the fildes. File descriptor fildes is obtained from an open, creat, dup, or fcntl call. Internal limitations may cause write to write fewer bytes than requested; the number of bytes actually written is indicated by the return value. Several calls to write may therefore be necessary to write out the contents of buf. On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. Upon return from write, the file pointer is incremented by the number of bytes actually written. On nonseeking devices, writing starts at the current position. The value of a file pointer associated with such a device is undefined. If the O_APPEND file-status flag set in open is on, the file pointer is set to end-of-file before each write. The file pointer remains unchanged and write fails if fildes is not a valid file descriptor open for writing [EBADF]. If you try to write more bytes than there is room for on the device, write writes as many bytes as possible. For example, if nbyte is 512 and there is room for 20 bytes more on the device, write writes 20 bytes and returns a value of 20. The next attempt to write a nonzero number of bytes will return an error [ENOSPC]. File descriptor 1 is opened by the MPW Shell as standard output; file descriptor 2, as standard error. Return value Upon successful completion, the number of bytes actually written is returned. Otherwise, –1 is returned and errno is set to indicate the error. See also creat, ferror, fread, lseek, open, stdio æKY closeæ æDT int myVariabel = close((int) fildes); æKY creatæ æDT int myVariable = creat((const char *)filename); æKY dupæ æDT int myVariable = dup((int) fildes); æKY faccessæ æDT int myVariablle =faccess((const char *)filename, (unsigned int) cmd, (long *)arg); æKY fcntlæ æDT int myVaraible = fcntl((int) fildes, (unsigned int) cmd, (int) arg); æKY lseekæ æDT long myVariable = lseek((int) fildes, (long int) offset, (int) whence); æKY openæ æDT int myVariable = open((const char *)filename, (int) oflag); æKY readæ æDT int myVariable = read((int) fildes, (char*) buf, (unsigned long) nbyte); æKY unlinkæ æDT int myVariable = unlink((const char *)fileName); æKY writeæ æDT int myVariable = write((int) fildes, (const char*) buf, (unsigned long) nbyte); æKY Files.h æKL AddDrive Allocate AllocContig CatMove CloseWD Create create DirCreate Eject eject FInitQueue flushvol FlushVol FSClose FSDelete fsdelete FSMakeFSSpec fsopen FSOpen FSpCatMove FSpCreate FSpDelete FSpDirCreate FSpExchangeFiles FSpGetFInfo FSpOpenDF FSpOpenRF FSpRename FSpRstFLock FSpSetFInfo FSpSetFLock FSRead fsrename FSWrite GetDrvQHdr GetEOF GetFInfo getfinfo GetFPos GetFSQHdr GetVCBQHdr getvinfo GetVInfo GetVol getvol GetVRefNum GetWDInfo HCreate HDelete HGetFInfo HGetVol HOpen HOpenDF HOpenRF HRename HRstFLock HSetFInfo HSetFLock HSetVol OpenDF OpenRF openrf OpenWD PBAllocate PBAllocateAsync PBAllocateSync PBAllocContig PBAllocContigAsync PBAllocContigSync PBCatMove PBCatMoveAsync PBCatMoveSync PBCatSearch PBCatSearchAsync PBCatSearchSync PBClose PBCloseAsync PBCloseSync PBCloseWD PBCloseWDAsync PBCloseWDSync PBCreate PBCreateAsync PBCreateFileIDRef PBCreateFileIDRefAsync PBCreateFileIDRefSync PBCreateSync PBDelete PBDeleteAsync PBDeleteFileIDRef PBDeleteFileIDRefAsync PBDeleteFileIDRefSync PBDeleteSync PBDirCreate PBDirCreateAsync PBDirCreateSync PBDTAddAPPL PBDTAddAPPLAsync PBDTAddAPPLSync PBDTAddIcon PBDTAddIconAsync PBDTAddIconSync PBDTCloseDown PBDTDelete PBDTDeleteAsync PBDTDeleteSync PBDTFlush PBDTFlushAsync PBDTFlushSync PBDTGetAPPL PBDTGetAPPLAsync PBDTGetAPPLSync PBDTGetComment PBDTGetCommentAsync PBDTGetCommentSync PBDTGetIcon PBDTGetIconAsync PBDTGetIconInfo PBDTGetIconInfoAsync PBDTGetIconInfoSync PBDTGetIconSync PBDTGetInfo PBDTGetInfoAsync PBDTGetInfoSync PBDTGetPath PBDTOpenInform PBDTRemoveAPPL PBDTRemoveAPPLAsync PBDTRemoveAPPLSync PBDTRemoveComment PBDTRemoveCommentAsync PBDTRemoveCommentSync PBDTReset PBDTResetAsync PBDTResetSync PBDTSetComment PBDTSetCommentAsync PBDTSetCommentSync PBEject PBExchangeFiles PBExchangeFilesAsync PBExchangeFilesSync PBFlushFile PBFlushFileAsync PBFlushFileSync PBFlushVol PBFlushVolAsync PBFlushVolSync PBGetAltAccess PBGetAltAccessAsync PBGetAltAccessSync PBGetCatInfo PBGetCatInfoAsync PBGetCatInfoSync PBGetEOF PBGetEOFAsync PBGetEOFSync PBGetFCBInfo PBGetFCBInfoAsync PBGetFCBInfoSync PBGetFInfo PBGetFInfoAsync PBGetFInfoSync PBGetForeignPrivs PBGetForeignPrivsAsync PBGetForeignPrivsSync PBGetFPos PBGetFPosAsync PBGetFPosSync PBGetVInfo PBGetVInfoAsync PBGetVInfoSync PBGetVol PBGetVolAsync PBGetVolMountInfo PBGetVolMountInfoSize PBGetVolSync PBGetWDInfo PBGetWDInfoAsync PBGetWDInfoSync PBHCopyFile PBHCopyFileAsync PBHCopyFileSync PBHCreate PBHCreateAsync PBHCreateSync PBHDelete PBHDeleteAsync PBHDeleteSync PBHGetDirAccess PBHGetDirAccessAsync PBHGetDirAccessSync PBHGetFInfo PBHGetFInfoAsync PBHGetFInfoSync PBHGetLogInInfo PBHGetLogInInfoAsync PBHGetLogInInfoSync PBHGetVInfo PBHGetVInfoAsync PBHGetVInfoSync PBHGetVol PBHGetVolAsync PBHGetVolParms PBHGetVolParmsAsync PBHGetVolParmsSync PBHGetVolSync PBHMapID PBHMapIDAsync PBHMapIDSync PBHMapName PBHMapNameAsync PBHMapNameSync PBHMoveRename PBHMoveRenameAsync PBHMoveRenameSync PBHOpen PBHOpenAsync PBHOpenDeny PBHOpenDenyAsync PBHOpenDenySync PBHOpenDF PBHOpenDFAsync PBHOpenDFSync PBHOpenRF PBHOpenRFAsync PBHOpenRFDeny PBHOpenRFDenyAsync PBHOpenRFDenySync PBHOpenRFSync PBHOpenSync PBHRename PBHRenameAsync PBHRenameSync PBHRstFLock PBHRstFLockAsync PBHRstFLockSync PBHSetDirAccess PBHSetDirAccessAsync PBHSetDirAccessSync PBHSetFInfo PBHSetFInfoAsync PBHSetFInfoSync PBHSetFLock PBHSetFLockAsync PBHSetFLockSync PBHSetVol PBHSetVolAsync PBHSetVolSync PBLockRange PBLockRangeAsync PBLockRangeSync PBMakeFSSpec PBMakeFSSpecAsync PBMakeFSSpecSync PBMountVol PBOffLine PBOpen PBOpenAsync PBOpenDF PBOpenDFAsync PBOpenDFSync PBOpenRF PBOpenRFAsync PBOpenRFSync PBOpenSync PBOpenWD PBOpenWDAsync PBOpenWDSync PBRead PBReadAsync PBReadSync PBRename PBRenameAsync PBRenameSync PBResolveFileIDRef PBResolveFileIDRefAsync PBResolveFileIDRefSync PBRstFLock PBRstFLockAsync PBRstFLockSync PBSetAltAccess PBSetAltAccessAsync PBSetAltAccessSync PBSetCatInfo PBSetCatInfoAsync PBSetCatInfoSync PBSetEOF PBSetEOFAsync PBSetEOFSync PBSetFInfo PBSetFInfoAsync PBSetFInfoSync PBSetFLock PBSetFLockAsync PBSetFLockSync PBSetForeignPrivs PBSetForeignPrivsAsync PBSetForeignPrivsSync PBSetFPos PBSetFPosAsync PBSetFPosSync PBSetFVers PBSetFVersAsync PBSetFVersSync PBSetVInfo PBSetVInfoAsync PBSetVInfoSync PBSetVol PBSetVolAsync PBSetVolSync PBUnlockRange PBUnlockRangeAsync PBUnlockRangeSync PBUnmountVol PBVolumeMount PBWrite PBWriteAsync PBWriteSync Rename rstflock RstFLock SetEOF SetFInfo setfinfo setflock SetFLock SetFPos SetVol setvol unmountvol UnmountVol AccessParam AFPVolMountInfo AFPVolMountInfoPtr alphaStage AppleShareMediaType bAccessCntl betaStage bHasBlankAccessPrivileges bHasBTreeMgr bHasCatSearch bHasCopyFile bHasDesktopMgr bHasExtFSVol bHasFileIDs bHasFolderLock bHasMoveRename bHasOpenDeny bHasPersonalAccessPrivileges bHasShortName bHasUserGroupList bLimitFCBs bLocalWList bNoBootBlks bNoDeskItems bNoLclSync bNoMiniFndr bNoSwitchTo bNoSysDir bNoVNEdit bTrshOffLine CatPositionRec CInfoPBPtr CInfoPBRec CInfoType CMovePBPtr CMovePBRec CntrlParam CopyParam CSParam CSParamPtr developStage DInfo DirInfo dirInfo DrvQEl DrvQElPtr DTPBPtr DTPBRec DXInfo FCBPBPtr FCBPBRec fDesktop fDisk fHasBundle FIDParam FileParam finalStage FInfo fInvisible fOnDesk ForeignPrivParam ForeignPrivParamPtr fsAtMark fsCurPerm fsFromLEOF fsFromMark fsFromStart fsRdPerm fsRdWrPerm fsRdWrShPerm fsRtDirID fsRtParID fsSBDrBkDat fsSBDrCrDat fsSBDrFndrInfo fsSBDrMdDat fsSBDrNmFls fsSBDrParID fsSBDrUsrWds fsSBFlAttrib fsSBFlBkDat fsSBFlCrDat fsSBFlFndrInfo fsSBFlLgLen fsSBFlMdDat fsSBFlParID fsSBFlPyLen fsSBFlRLgLen fsSBFlRPyLen fsSBFlXFndrInfo fsSBFullName fsSBNegate fsSBPartialName FSSpec FSSpecArray FSSpecArrayHandle FSSpecArrayPtr FSSpecHandle FSSpecPtr fsUnixPriv fsWrPerm fTrash FXInfo GetVolParmsInfoBuffer HFileInfo hFileInfo HFileParam HIOParam HParamBlockRec HParmBlkPtr HVolumeParam ioDirFlg ioDirMask IOParam kEncryptPassword kLarge4BitIcon kLarge4BitIconSize kLarge8BitIcon kLarge8BitIconSize kLargeIcon kLargeIconSize kNoUserAuthentication kPassword kSmall4BitIcon kSmall4BitIconSize kSmall8BitIcon kSmall8BitIconSize kSmallIcon kSmallIconSize kTwoWayEncryptPassword MultiDevParam NumVersion ObjParam ParamBlockHeader ParamBlockRec ParmBlkPtr rdVerify SlotDevParam VCB VersRec VersRecHndl VersRecPtr VolMountInfoHeader VolMountInfoPtr VolumeParam VolumeType WDParam WDPBPtr WDPBRec æKY fsAtMark æFc Files.h æT æD fsAtMark = 0, æC IOPosMode and ioPosOffset specify the position of the mark for Read, Write, LockRng, UnlockRng, and SetFPos calls. IOPosMode contains the positioning mode; bits 0 and 1 indicate how to position the mark, and you can use the following predefined constants to set or test their value: #define fsAtMark 0 /*at current mark*/ #define fsFromStart 1 /*set mark relative to beginning of file*/ #define fsFromLEOF 2 /*set mark relative to logical end-of-file*/ #define fsFromMark 3 /*set mark relative to current mark*/ If you specify fsAtMark, ioPosOffset is ignored and the operation begins wherever the mark is currently positioned. If you choose to set the mark (relative to either the beginning of the file, the logical end-of-file, or the current mark), ioPosOffset must specify the byte offset from the chosen point (either positive or negative) where the operation should begin. Note: Advanced programmers: Bit 7 of ioPosMode is the newline flag; it’s set if read operations should terminate at a newline character. The ASCII code of the newline character is specified in the high-order byte of ioPosMode. If the newline flag is set, the data will be read one byte at a time until the newline character is encountered, ioReqCount bytes have been read, or the end-of-file is reached. If the newline flag is clear, the data will be read one byte at a time until ioReqCount bytes have been read or the end-of-file is reached. æKY fOnDesk æFc Files.h æT æD fOnDesk = 1, æC æKY fsCurPerm æFc Files.h æT æD fsCurPerm = 0, æC IOPermssn requests permission to read or write via an access path, and must contain one of the following values: #define fsCurPerm 0 /*whatever is currently allowed*/ #define fsRdPerm 1 /*request for read permission only*/ #define fsWrPerm 2 /*request for write permission*/ #define fsRdWrPerm 3 /*request for exclusive read/write permission*/ #define fsRdWrShPerm 4 /*request for shared read/write permission*/ This request is compared with the open permission of the file. If the open permission doesn’t allow I/O as requested, a result code indicating the error is returned. Warning: To ensure data integrity be sure to lock the portion of the file you’ll be using if you specify shared write permission. æKY fHasBundle æFc Files.h æT æD fHasBundle = 8192, æC æKY fsRdPerm æFc Files.h æT æD fsRdPerm = 1, æC æKY fInvisible æFc Files.h æT æD fInvisible = 16384, æC æKY fTrash æFc Files.h æT æD fTrash = -3, æC æKY fsWrPerm æFc Files.h æT æD fsWrPerm = 2, æC æKY fDesktop æFc Files.h æT æD fDesktop = -2, æC æKY fsRdWrPerm æFc Files.h æT æD fsRdWrPerm = 3, æC æKY fDisk æFc Files.h æT æD fDisk = 0, æC æKY fsRdWrShPerm æFc Files.h æT æD fsRdWrShPerm = 4, æC æKY fsFromStart æFc Files.h æT æD fsFromStart = 1, æC æKY fsFromLEOF æFc Files.h æT æD fsFromLEOF = 2, æC æKY fsFromMark æFc Files.h æT æD fsFromMark = 3, æC æKY rdVerify æFc Files.h æT æD rdVerify = 64, æC To have the File Manager verify that all data written to a volume exactly matches the data in memory, make a Read call right after the Write call. The parameters for a read-verify operation are the same as for a standard Read call, except that the following constant must be added to the positioning mode: #define rdVerify 64 /*read-verify mode*/ The result code ioErr is returned if any of the data doesn’t match. æKY ioDirFlg æFc Files.h æT æD ioDirFlg = 3, /*see IM IV-125*/ æC æKY ioDirMask æFc Files.h æT æD ioDirMask = 0x10, æC æKY fsRtParID æFc Files.h æT æD fsRtParID = 1, æC æKY fsRtDirID æFc Files.h æT æD fsRtDirID = 2, æC æKY fsSBPartialName æFc Files.h æT æD fsSBPartialName = 1, æC æKY fsSBFullName æFc Files.h æT æD fsSBFullName = 2, æC æKY fsSBFlAttrib æFc Files.h æT æD fsSBFlAttrib = 4, æC æKY fsSBFlFndrInfo æFc Files.h æT æD fsSBFlFndrInfo = 8, æC æKY fsSBFlLgLen æFc Files.h æT æD fsSBFlLgLen = 32, æC æKY fsSBFlPyLen æFc Files.h æT æD fsSBFlPyLen = 64, æC æKY fsSBFlRLgLen æFc Files.h æT æD fsSBFlRLgLen = 128, æC æKY fsSBFlRPyLen æFc Files.h æT æD fsSBFlRPyLen = 256, æC æKY fsSBFlCrDat æFc Files.h æT æD fsSBFlCrDat = 512, æC æKY fsSBFlMdDat æFc Files.h æT æD fsSBFlMdDat = 1024, æC æKY fsSBFlBkDat æFc Files.h æT æD fsSBFlBkDat = 2048, æC æKY fsSBFlXFndrInfo æFc Files.h æT æD fsSBFlXFndrInfo = 4096, æC æKY fsSBFlParID æFc Files.h æT æD fsSBFlParID = 8192, æC æKY fsSBNegate æFc Files.h æT æD fsSBNegate = 16384, æC æKY fsSBDrUsrWds æFc Files.h æT æD fsSBDrUsrWds = 8, æC æKY fsSBDrNmFls æFc Files.h æT æD fsSBDrNmFls = 16, æC æKY fsSBDrCrDat æFc Files.h æT æD fsSBDrCrDat = 512, æC æKY fsSBDrMdDat æFc Files.h æT æD fsSBDrMdDat = 1024, æC æKY fsSBDrBkDat æFc Files.h æT æD fsSBDrBkDat = 2048, æC æKY fsSBDrFndrInfo æFc Files.h æT æD fsSBDrFndrInfo = 4096, æC æKY fsSBDrParID æFc Files.h æT æD fsSBDrParID = 8192, æC æKY bLimitFCBs æFc Files.h æT æD bLimitFCBs = 31, æC æKY bLocalWList æFc Files.h æT æD bLocalWList = 30, æC æKY bNoMiniFndr æFc Files.h æT æD bNoMiniFndr = 29, æC æKY bNoVNEdit æFc Files.h æT æD bNoVNEdit = 28, æC æKY bNoLclSync æFc Files.h æT æD bNoLclSync = 27, æC æKY bTrshOffLine æFc Files.h æT æD bTrshOffLine = 26, æC æKY bNoSwitchTo æFc Files.h æT æD bNoSwitchTo = 25, æC æKY bNoDeskItems æFc Files.h æT æD bNoDeskItems = 20, æC æKY bNoBootBlks æFc Files.h æT æD bNoBootBlks = 19, æC æKY bAccessCntl æFc Files.h æT æD bAccessCntl = 18, æC æKY bNoSysDir æFc Files.h æT æD bNoSysDir = 17, æC æKY bHasExtFSVol æFc Files.h æT æD bHasExtFSVol = 16, æC æKY bHasOpenDeny æFc Files.h æT æD bHasOpenDeny = 15, æC æKY bHasCopyFile æFc Files.h æT æD bHasCopyFile = 14, æC æKY bHasMoveRename æFc Files.h æT æD bHasMoveRename = 13, æC æKY bHasDesktopMgr æFc Files.h æT æD bHasDesktopMgr = 12, æC æKY bHasShortName æFc Files.h æT æD bHasShortName = 11, æC æKY bHasFolderLock æFc Files.h æT æD bHasFolderLock = 10, æC æKY bHasPersonalAccessPrivileges æFc Files.h æT æD bHasPersonalAccessPrivileges = 9, æC æKY bHasUserGroupList æFc Files.h æT æD bHasUserGroupList = 8, æC æKY bHasCatSearch æFc Files.h æT æD bHasCatSearch = 7, æC æKY bHasFileIDs æFc Files.h æT æD bHasFileIDs = 6, æC æKY bHasBTreeMgr æFc Files.h æT æD bHasBTreeMgr = 5, æC æKY bHasBlankAccessPrivileges æFc Files.h æT æD bHasBlankAccessPrivileges = 4, æC æKY kLargeIcon æFc Files.h æT æD kLargeIcon = 1, æC æKY kLarge4BitIcon æFc Files.h æT æD kLarge4BitIcon = 2, æC æKY kLarge8BitIcon æFc Files.h æT æD kLarge8BitIcon = 3, æC æKY kSmallIcon æFc Files.h æT æD kSmallIcon = 4, æC æKY kSmall4BitIcon æFc Files.h æT æD kSmall4BitIcon = 5, æC æKY kSmall8BitIcon æFc Files.h æT æD kSmall8BitIcon = 6, æC æKY kLargeIconSize æFc Files.h æT æD kLargeIconSize = 256, æC æKY kLarge4BitIconSize æFc Files.h æT æD kLarge4BitIconSize = 512, æC æKY kLarge8BitIconSize æFc Files.h æT æD kLarge8BitIconSize = 1024, æC æKY kSmallIconSize æFc Files.h æT æD kSmallIconSize = 64, æC æKY kSmall4BitIconSize æFc Files.h æT æD kSmall4BitIconSize = 128, æC æKY kSmall8BitIconSize æFc Files.h æT æD kSmall8BitIconSize = 256, æC æKY fsUnixPriv æFc Files.h æT æD fsUnixPriv = 1, æC æKY developStage æFc Files.h æT æD developStage = 0x20, æC æKY alphaStage æFc Files.h æT æD alphaStage = 0x40, æC æKY betaStage æFc Files.h æT æD betaStage = 0x60, æC æKY finalStage æFc Files.h æT æD finalStage = 0x80, æC æKY kNoUserAuthentication æFc Files.h æT æD kNoUserAuthentication = 1, æC æKY kPassword æFc Files.h æT æD kPassword = 2, æC æKY kEncryptPassword æFc Files.h æT æD kEncryptPassword = 3, æC æKY kTwoWayEncryptPassword æFc Files.h æT æD kTwoWayEncryptPassword = 6, æC æKY CInfoType hFileInfo dirInfo æFc Files.h æT enum æD enum {hFileInfo,dirInfo}; typedef unsigned char CInfoType; æC æKY FInfo æFc Files.h æT struct æD struct FInfo { OSType fdType; /*the type of the file*/ OSType fdCreator; /*file's creator*/ unsigned short fdFlags; /*flags ex. hasbundle,invisible,locked, etc.*/ Point fdLocation; /*file's location in folder*/ short fdFldr; /*folder containing file*/ }; typedef struct FInfo FInfo; æC æKY FXInfo æFc Files.h æT struct æD struct FXInfo { short fdIconID; /* Icon ID*/ short fdUnused[3]; /*unused but reserved 6 bytes*/ char fdScript; /* Script flag and number */ char fdXFlags; short fdComment; /* Comment ID*/ long fdPutAway; /* Home Dir ID*/ }; typedef struct FXInfo FXInfo; æC On hierarchical volumes, in addition to the FInfo record, the following information about files is maintained for the Finder: æKY DInfo æFc Files.h æT struct æD struct DInfo { Rect frRect; /*folder rect*/ unsigned short frFlags; /*Flags*/ Point frLocation; /*folder location*/ short frView; /*folder view*/ }; typedef struct DInfo DInfo; æC On hierarchical volumes, the following information about directories is maintained for the Finder: DInfo = RECORD frRect: Rect; {folder's rectangle} frFlags: INTEGER; {flags} frLocation: Point; {folder's location} frView: INTEGER; {folder's view} END; DXInfo = RECORD frScroll: Point; {scroll position} frOpenChain: LONGINT; {directory ID chain of open folders} frUnused: INTEGER; {reserved} frComment: INTEGER; {comment ID} frPutAway: LONGINT; {directory ID} END; When a file (or folder) is moved to the desktop on a hierarchical volume, it’s actually moved to the root level of the file directory. (This permits all the desktop icons to be enumerated by one simple scan of the root.) The fOnDesk bit of fdFlags is set. FDPutAway (or frPutAway for directories) contains the directory ID of the folder that originally contained the file (or folder); this allows the file (or folder) to be returned there from the desktop. æKY DXInfo æFc Files.h æT struct æD struct DXInfo { Point frScroll; /*scroll position*/ long frOpenChain; /*DirID chain of open folders*/ char frScript; /* Script flag and number */ char frXFlags; short frComment; /*comment*/ long frPutAway; /*DirID*/ }; typedef struct DXInfo DXInfo; æC æKY GetVolParmsInfoBuffer æFc Files.h æT struct æD struct GetVolParmsInfoBuffer { short vMVersion; /*version number*/ long vMAttrib; /*bit vector of attributes (see vMAttrib constants)*/ Handle vMLocalHand; /*handle to private data*/ long vMServerAdr; /*AppleTalk server address or zero*/ long vMVolumeGrade; /*approx. speed rating or zero if unrated*/ short vMForeignPrivID; /*foreign privilege model supported or zero if none*/ }; typedef struct GetVolParmsInfoBuffer GetVolParmsInfoBuffer; æC æKY ParamBlockHeader æFc Files.h æT struct æD #define ParamBlockHeader \ QElemPtr qLink; /*queue link in header*/\ short qType; /*type byte for safety check*/\ short ioTrap; /*FS: the Trap*/\ Ptr ioCmdAddr; /*FS: address to dispatch to*/\ ProcPtr ioCompletion; /*completion routine addr (0 for synch calls)*/\ OSErr ioResult; /*result code*/\ StringPtr ioNamePtr; /*ptr to Vol:FileName string*/\ short ioVRefNum; /*volume refnum (DrvNum for Eject and MountVol)*/ æC æKY IOParam æFc Files.h æT struct æD struct IOParam { ParamBlockHeader short ioRefNum; /*refNum for I/O operation*/ char ioVersNum; /*version number*/ char ioPermssn; /*Open: permissions (byte)*/ Ptr ioMisc; /*Rename: new name (GetEOF,SetEOF: logical end of file) (Open: optional ptr to buffer) (SetFileType: new type)*/ Ptr ioBuffer; /*data buffer Ptr*/ long ioReqCount; /*requested byte count; also = ioNewDirID*/ long ioActCount; /*actual byte count completed*/ short ioPosMode; /*initial file positioning*/ long ioPosOffset; /*file position offset*/ }; typedef struct IOParam IOParam; æC æKY FileParam æFc Files.h æT struct æD struct FileParam { ParamBlockHeader short ioFRefNum; /*reference number*/ char ioFVersNum; /*version number*/ char filler1; short ioFDirIndex; /*GetFInfo directory index*/ unsigned char ioFlAttrib; /*GetFInfo: in-use bit=7, lock bit=0*/ unsigned char ioFlVersNum; /*file version number*/ FInfo ioFlFndrInfo; /*user info*/ unsigned long ioFlNum; /*GetFInfo: file number; TF- ioDirID*/ unsigned short ioFlStBlk; /*start file block (0 if none)*/ long ioFlLgLen; /*logical length (EOF)*/ long ioFlPyLen; /*physical length*/ unsigned short ioFlRStBlk; /*start block rsrc fork*/ long ioFlRLgLen; /*file logical length rsrc fork*/ long ioFlRPyLen; /*file physical length rsrc fork*/ unsigned long ioFlCrDat; /*file creation date& time (32 bits in secs)*/ unsigned long ioFlMdDat; /*last modified date and time*/ }; typedef struct FileParam FileParam; æC æKY VolumeParam æFc Files.h æT struct æD struct VolumeParam { ParamBlockHeader long filler2; short ioVolIndex; /*volume index number*/ unsigned long ioVCrDate; /*creation date and time*/ unsigned long ioVLsBkUp; /*last backup date and time*/ unsigned short ioVAtrb; /*volume attrib*/ unsigned short ioVNmFls; /*number of files in directory*/ unsigned short ioVDirSt; /*start block of file directory*/ short ioVBlLn; /*GetVolInfo: length of dir in blocks*/ unsigned short ioVNmAlBlks; /*GetVolInfo: num blks (of alloc size)*/ long ioVAlBlkSiz; /*GetVolInfo: alloc blk byte size*/ long ioVClpSiz; /*GetVolInfo: bytes to allocate at a time*/ unsigned short ioAlBlSt; /*starting disk(512-byte) block in block map*/ unsigned long ioVNxtFNum; /*GetVolInfo: next free file number*/ unsigned short ioVFrBlk; /*GetVolInfo: # free alloc blks for this vol*/ }; typedef struct VolumeParam VolumeParam; æC æKY CntrlParam æFc Files.h æT struct æD struct CntrlParam { QElem *qLink; /*queue link in header*/ short qType; /*type byte for safety check*/ short ioTrap; /*FS: the Trap*/ Ptr ioCmdAddr; /*FS: address to dispatch to*/ ProcPtr ioCompletion; /*completion routine addr (0 for synch calls)*/ OSErr ioResult; /*result code*/ StringPtr ioNamePtr; /*ptr to Vol:FileName string*/ short ioVRefNum; /*volume refnum (DrvNum for Eject and MountVol)*/ short ioCRefNum; /*refNum for I/O operation*/ short csCode; /*word for control status code*/ short csParam[11]; /*operation-defined parameters*/ }; typedef struct CntrlParam CntrlParam; æC æKY SlotDevParam æFc Files.h æT struct æD struct SlotDevParam { ParamBlockHeader short ioRefNum; char ioVersNum; char ioPermssn; Ptr ioMix; short ioFlags; char ioSlot; char ioID; }; typedef struct SlotDevParam SlotDevParam; æC æKY MultiDevParam æFc Files.h æT struct æD struct MultiDevParam { ParamBlockHeader short ioRefNum; char ioVersNum; char ioPermssn; Ptr ioMix; short ioFlags; Ptr ioSEBlkPtr; }; typedef struct MultiDevParam MultiDevParam; æC æKY ParamBlockRec ParmBlkPtr æFc Files.h æT struct æD union ParamBlockRec { IOParam ioParam; FileParam fileParam; VolumeParam volumeParam; CntrlParam cntrlParam; SlotDevParam slotDevParam; MultiDevParam multiDevParam; }; typedef union ParamBlockRec ParamBlockRec; typedef ParamBlockRec *ParmBlkPtr; æC »FileParam Variant ( ParamBlockRec and HParamBlockRec) The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with one exception: The field ioDirID in HParamBlockRec is called ioFlNum in ParamBlockRec. The fields of the fileParam variant of HParamBlockRec are as follows: •••Refer to Technical Note #204:••• fileParam: (ioFRefNum: INTEGER; {path reference number} ioFVersNum: SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} ioFlVersNum: SignedByte; {version number} ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LONGINT; {directory ID or file number} ioFlStBlk: INTEGER; {first allocation block of data fork} ioFlLgLen: LONGINT; {logical end-of-file of data fork} ioFlPyLen: LONGINT; {physical end-of-file of data fork} ioFlRStBlk: INTEGER; {first allocation block of resource fork} ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} ioFlCrDat: LONGINT; {date and time of creation} ioFlMdDat: LONGINT); {date and time of last modification} IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the files in a given directory. Warning: When used with GetFileInfo, ioFDirIndex will index only the files in a directory. To index both files and directories, you can use ioFDirIndex with PBGetCatInfo. IOFlAttrib contains the following file attributes: Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open When passed to a routine, ioDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) When returned from a routine, ioDirID contains the file number of a file; most programmers needn’t be concerned with file numbers, but those interested can read the section “Data Organization on Volumes”. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty, respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat and ioFlMdDat fields are specified in seconds since midnight, January 1, 1904. »VolumeParam Variant (ParamBlockRec) When you call GetVolInfo, you’ll use the volumeParam variant of ParamBlockRec: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsBkUp: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVDirSt: INTEGER; {first block of directory} ioVBlLn: INTEGER; {length of directory in blocks} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtFNum: LONGINT; {next unused file number} ioVFrBlk: INTEGER); {number of unused allocation blocks} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsBkUp contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: The name ioVLsBkUp is actually a misnomer; this field has always contained the date and time of the last modification to the volume, not the last backup. Most programmers needn’t be concerned with the remaining parameters, but interested programmers can read the section “Data Organization on Volumes”. »VolumeParam Variant (HParamBlockRec) When you call HGetVInfo and SetVolInfo, you’ll use the volumeParam variant of HParamBlockRec. This is a superset of the volumeParam variant of ParamBlockRec; the names and functions of certain fields have been changed, and new fields have been added: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsMod: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVBitMap: INTEGER; {first block of volume bit map} ioAllocPtr: INTEGER; {block at which next new file starts} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtCNID: LONGINT; {next unused file number} ioVFrBlk: INTEGER; {number of unused allocation blocks} ioVSigWord: INTEGER; {volume signature} ioVDrvInfo: INTEGER; {drive number} ioVDRefNum: INTEGER; {driver reference number} ioVFSID: INTEGER; {file system handling this volume} ioVBkUp: LONGINT; {date and time of last backup} ioVSeqNum: INTEGER; {used internally} ioVWrCnt LONGINT; {volume write count} ioVFilCnt: LONGINT; {number of files on volume} ioVDirCnt: LONGINT; {number of directories on volume} ioVFndrInfo: ARRAY[1..8] OF LONGINT); {information used by the Finder} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsMod contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: IOVLsMod replaces the field ioVLsBkUp in ParamBlockRec. The name ioVLsBkUp was actually a misnomer; this field has always contained the date and time of the last modification, not the last backup. Another field, ioVBkUp, contains the date and time of the last backup. IOVClpSiz can be used to set the volume clump size in bytes; it’s used for files that don’t have a clump size defined as part of their file information in the catalog. To promote file contiguity and avoid fragmentation, space is allocated to a file not in allocation blocks but in clumps. A clump is a group of contiguous allocation blocks. The clump size is always a multiple of the allocation block size; it’s the minimum number of bytes to allocate each time the Allocate function is called or the end-of-file is reached during the Write routine. IOVSigWord contains a signature word identifying the type of volume; it’s $D2D7 for flat directory volumes and $4244 for hierarchical directory volumes. The drive number of the drive containing the volume is returned in ioDrvInfo. For on-line volumes, ioVDRefNum returns the reference number of the I/O driver for the drive identified by ioDrvInfo. IOVFSID is the file-system identifier. It indicates which file system is servicing the volume; it’s 0 for File Manager volumes and nonzero for volumes handled by an external file system. IOVBkUp specifies the date and time the volume was last backed up (it’s 0 if never backed up). IOVNmFls contains the number of files in the root directory. IOVFilCnt contains the total number of files on the volume, while ioVDirCnt contains the total number of directories (not including the root directory). Most programmers needn’t be concerned with the other parameters, but interested programmers can read the section “Data Organization on Volumes”. HParamBlockRec, described above, has been extended to support a shared environment with the addition of AccessParam, ObjParam, CopyParam, and WDParam, as shown below. (The complete HParamBlockRec data type is shown in the summary.) AccessParam: (filler3: INTEGER; ioDenyModes: INTEGER; {access rights data} filler4: INTEGER; filler5: Signed Byte; ioACUser: Signed Byte; {access rights for directory only} filler6: LONGINT; ioACOwnerID: LONGINT; {owner ID} ioACGroupID: LONGINT; {group ID} ioACAccess: LONGINT); {access rights} ObjParam: (filler7: INTEGER; ioObjType: INTEGER; {function code} ioObjNamePtr: Ptr; {ptr to returned creator/group name} ioObjID: LONGINT; {creator/group ID} ioReqCount: LONGINT; {size of buffer area} ioActCount: LONGINT); {length of vol parms data} CopyParam: (ioDstVRefNum: INTEGER; {destination vol identifier} filler8: INTEGER; ioNewName: Ptr; {ptr to destination pathname} ioCopyName: Ptr; {ptr to optional name} ioNewDirID: LONGINT); {destination directory ID} WDParam: (filler9: INTEGER; ioWDIndex: INTEGER; ioWDProcID: LONGINT; ioWDVRefNum: INTEGER; filler10: INTEGER; filler11: LONGINT; filler12: LONGINT; filler13: LONGINT; ioWDDirID: LONGINT); æKY HFileInfo æFc Files.h æT struct æD struct HFileInfo { ParamBlockHeader short ioFRefNum; char ioFVersNum; char filler1; short ioFDirIndex; char ioFlAttrib; char filler2; FInfo ioFlFndrInfo; long ioDirID; unsigned short ioFlStBlk; long ioFlLgLen; long ioFlPyLen; unsigned short ioFlRStBlk; long ioFlRLgLen; long ioFlRPyLen; unsigned long ioFlCrDat; unsigned long ioFlMdDat; unsigned long ioFlBkDat; FXInfo ioFlXFndrInfo; long ioFlParID; long ioFlClpSiz; }; typedef struct HFileInfo HFileInfo; æC æKY DirInfo æFc Files.h æT struct æD struct DirInfo { ParamBlockHeader short ioFRefNum; short filler1; short ioFDirIndex; char ioFlAttrib; char filler2; DInfo ioDrUsrWds; long ioDrDirID; unsigned short ioDrNmFls; short filler3[9]; unsigned long ioDrCrDat; unsigned long ioDrMdDat; unsigned long ioDrBkDat; DXInfo ioDrFndrInfo; long ioDrParID; }; typedef struct DirInfo DirInfo; æC æKY CInfoPBRec CInfoPBPtr æFc Files.h æT struct æD union CInfoPBRec { HFileInfo hFileInfo; DirInfo dirInfo; }; typedef union CInfoPBRec CInfoPBRec; typedef CInfoPBRec *CInfoPBPtr; æC »CInfoPBRec The routines GetCatInfo and SetCatInfo are used for getting and setting information about the files and directories within a directory. With files, you’ll use the following 19 additional fields after the standard eight fields in the parameter block record CInfoPBRec: ioFRefNum: INTEGER; {path reference number} ioFVersNum: SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} filler2: SignedByte; {not used} hFileInfo: (ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LONGINT; {directory ID or file number} ioFlStBlk: INTEGER; {first allocation block of data fork} ioFlLgLen: LONGINT; {logical end-of-file of data fork} ioFlPyLen: LONGINT; {physical end-of-file of data fork} ioFlRStBlk: INTEGER; {first allocation block of resource fork} ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} ioFlCrDat: LONGINT; {date and time of creation} ioFlMdDat: LONGINT; {date and time of last modification} ioFlBkDat: LONGINT; {date and time of last backup} ioFlXFndrInfo: FXInfo; {additional information used by the Finder} ioFlParID: LONGINT; {file's parent directory ID (integer)} ioFlClpSiz: LONGINT); {file's clump size} •••Refer to Technical Note #69:••• IOFDirIndex can be used with the function PBGetCatInfo to index through the files and directories in a given directory. For each iteration of the function, you can determine whether it’s a file or a directory by testing bit 4 (the fifth least significant bit) of ioFlAttrib. You can test for a directory by using the Toolbox Utilities BitTst function in the following manner (remember, the Toolbox Utilities routines reverse the standard 68000 notation): BitTst(@myCInfoRec.ioFlAttrib,3) IOFlAttrib contains the following attributes: Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open When passed to a routine, ioDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) Warning: With files, ioDirID returns the file number of the file; when indexing with GetCatInfo, you’ll need to reset this field for each iteration. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty, respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat, ioFlMdDat, and ioFlBkDat fields are specified in seconds since midnight, January 1, 1904. IOFlParID contains the directory ID of the file’s parent. IOFlClpSiz is the clump size to be used when writing the file; if it’s 0, the volume’s clump size is used when the file is opened. With directories, you’ll use the following 14 additional fields after the standard eight fields in the parameter block record CInfoPBRec: ioFRefNum: INTEGER; {file reference number} ioFVersNum SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} filler2: SignedByte; {not used} dirInfo: (ioDrUsrWds: DInfo; {information used by the Finder} ioDrDirID: LONGINT; {directory ID} ioDrNmFls: INTEGER; {number of files in directory} filler3: ARRAY[1..9] OF INTEGER; {not used} ioDrCrDat: LONGINT; {date and time of creation} ioDrMdDat: LONGINT; {date and time of last modification} ioDrBkDat: LONGINT; {date and time of last backup} ioDrFndrInfo: DXInfo; {additional information used by the Finder} ioDrParID: LONGINT); {directory's parent directory ID (integer)} IOFDirIndex can be used with the function PBGetCatInfo to index through the files and directories in a given directory. For each iteration of the function, you can determine whether it’s a file or a directory by testing bit 4 of ioFlAttrib. When passed to a routine, ioDrDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) With directories, ioDrDirID returns the directory ID of the directory. IODrNmFls is the number of files and directories contained in this directory (the valence of the directory). The date and time in the ioDrCrDat, ioDrMdDat, and ioDrBkDat fields are specified in seconds since midnight, January 1, 1904. IODrParID contains the directory ID of the directory’s parent. æKY HIOParam æFc Files.h æT struct æD struct HIOParam { ParamBlockHeader short ioRefNum; char ioVersNum; char ioPermssn; Ptr ioMisc; Ptr ioBuffer; long ioReqCount; long ioActCount; short ioPosMode; long ioPosOffset; short filler1; }; typedef struct HIOParam HIOParam; æC æKY HFileParam æFc Files.h æT struct æD struct HFileParam { ParamBlockHeader short ioFRefNum; char ioFVersNum; char filler1; short ioFDirIndex; char ioFlAttrib; char ioFlVersNum; FInfo ioFlFndrInfo; long ioDirID; unsigned short ioFlStBlk; long ioFlLgLen; long ioFlPyLen; unsigned short ioFlRStBlk; long ioFlRLgLen; long ioFlRPyLen; unsigned long ioFlCrDat; unsigned long ioFlMdDat; }; typedef struct HFileParam HFileParam; æC æKY HVolumeParam æFc Files.h æT struct æD struct HVolumeParam { ParamBlockHeader long filler2; short ioVolIndex; unsigned long ioVCrDate; unsigned long ioVLsMod; short ioVAtrb; unsigned short ioVNmFls; short ioVBitMap; short ioAllocPtr; unsigned short ioVNmAlBlks; long ioVAlBlkSiz; long ioVClpSiz; short ioAlBlSt; long ioVNxtCNID; unsigned short ioVFrBlk; unsigned short ioVSigWord; short ioVDrvInfo; short ioVDRefNum; short ioVFSID; unsigned long ioVBkUp; unsigned short ioVSeqNum; long ioVWrCnt; long ioVFilCnt; long ioVDirCnt; long ioVFndrInfo[8]; }; typedef struct HVolumeParam HVolumeParam; æC æKY AccessParam æFc Files.h æT struct æD struct AccessParam { ParamBlockHeader short filler3; short ioDenyModes; /*access rights data*/ short filler4; char filler5; char ioACUser; /*access rights for directory only*/ long filler6; long ioACOwnerID; /*owner ID*/ long ioACGroupID; /*group ID*/ long ioACAccess; /*access rights*/ }; typedef struct AccessParam AccessParam; æC æKY ObjParam æFc Files.h æT struct æD struct ObjParam { ParamBlockHeader short filler7; short ioObjType; /*function code*/ StringPtr ioObjNamePtr; /*ptr to returned creator/group name*/ long ioObjID; /*creator/group ID*/ long ioReqCount; /*size of buffer area*/ long ioActCount; /*length of vol parms data*/ }; typedef struct ObjParam ObjParam; æC æKY CopyParam æFc Files.h æT struct æD struct CopyParam { ParamBlockHeader short ioDstVRefNum; /*destination vol identifier*/ short filler8; StringPtr ioNewName; /*ptr to destination pathname*/ StringPtr ioCopyName; /*ptr to optional name*/ long ioNewDirID; /*destination directory ID*/ long filler14; long filler15; long ioDirID; /*same as in FileParam*/ }; typedef struct CopyParam CopyParam; æC æKY WDParam æFc Files.h æT struct æD struct WDParam { ParamBlockHeader short filler9; short ioWDIndex; long ioWDProcID; short ioWDVRefNum; short filler10; long filler11; long filler12; long filler13; long ioWDDirID; }; typedef struct WDParam WDParam; æC æKY FIDParam æFc Files.h æT struct æD struct FIDParam { ParamBlockHeader long filler1; StringPtr ioDestNamePtr; /* dest file name */ long filler2; long ioDestDirID; /* dest file's directory id */ long filler3; long filler4; long ioSrcDirID; /* source file's directory id */ short filler5; long ioFileID; /* file ID */ }; typedef struct FIDParam FIDParam; æC æKY CatPositionRec æFc Files.h æT struct æD struct CatPositionRec { long initialize; short priv[6]; }; typedef struct CatPositionRec CatPositionRec; æC æKY FSSpec FSSpecPtr FSSpecHandle æFc Files.h æT struct æD struct FSSpec { short vRefNum; long parID; Str63 name; }; typedef struct FSSpec FSSpec; typedef FSSpec *FSSpecPtr, **FSSpecHandle; æC æKY FSSpecArray FSSpecArrayPtr FSSpecArrayHandle æFc Files.h æT struct æD typedef FSSpecPtr FSSpecArrayPtr; /* pointer to array of FSSpecs */ æC æKY VolumeType æFc Files.h æT typedef æD typedef OSType VolumeType; æC æKY AppleShareMediaType æFc Files.h æT #define æD #define AppleShareMediaType 'afpm' /* the signature for AppleShare */ æC æKY VolMountInfoHeader VolMountInfoPtr æFc Files.h æT struct æD struct VolMountInfoHeader { short length; /* length of location data (including self) */ VolumeType media; /* type of media . Variable length data follows */ }; typedef struct VolMountInfoHeader VolMountInfoHeader; typedef VolMountInfoHeader *VolMountInfoPtr; æC æKY AFPVolMountInfo AFPVolMountInfoPtr æFc Files.h æT struct æD struct AFPVolMountInfo { short length; /* length of location data (including self) */ VolumeType media; /* type of media */ short flags; /* bits for no messages, no reconnect */ char nbpInterval; /* NBP Interval parameter (IM2, p.322) */ char nbpCount; /* NBP Interval parameter (IM2, p.322) */ short uamType; /* User Authentication Method */ short zoneNameOffset; /* short positive offset from start of struct to Zone Name */ short serverNameOffset; /* offset to pascal Server Name string */ short volNameOffset; /* offset to pascal Volume Name string */ short userNameOffset; /* offset to pascal User Name string */ short userPasswordOffset; /* offset to pascal User Password string */ short volPasswordOffset; /* offset to pascal Volume Password string */ char AFPData[144]; /*variable length data may follow*/ }; typedef struct AFPVolMountInfo AFPVolMountInfo; typedef AFPVolMountInfo *AFPVolMountInfoPtr; æC æKY CSParam CSParamPtr æFc Files.h æT struct æD struct CSParam { ParamBlockHeader FSSpecPtr ioMatchPtr; /* match array */ long ioReqMatchCount; /* maximum allowable matches */ long ioActMatchCount; /* actual match count */ long ioSearchBits; /* search criteria selector */ CInfoPBPtr ioSearchInfo1; /* search values and range lower bounds */ CInfoPBPtr ioSearchInfo2; /* search values and range upper bounds */ long ioSearchTime; /* length of time to run search */ CatPositionRec ioCatPosition; /* current position in the catalog */ Ptr ioOptBuffer; /* optional performance enhancement buffer */ long ioOptBufSize; /* size of buffer pointed to by ioOptBuffer */ }; typedef struct CSParam CSParam; typedef CSParam *CSParamPtr; æC æKY DTPBRec DTPBPtr æFc Files.h æT struct æD struct DTPBRec { ParamBlockHeader short ioDTRefNum; /* desktop refnum */ short ioIndex; long ioTagInfo; Ptr ioDTBuffer; long ioDTReqCount; long ioDTActCount; char ioFiller1; char ioIconType; short ioFiller2; long ioDirID; OSType ioFileCreator; OSType ioFileType; long ioFiller3; long ioDTLgLen; long ioDTPyLen; short ioFiller4[14]; long ioAPPLParID; }; typedef struct DTPBRec DTPBRec; typedef DTPBRec *DTPBPtr; æC æKY ForeignPrivParam ForeignPrivParamPtr æFc Files.h æT struct æD struct ForeignPrivParam { ParamBlockHeader long ioFiller1; long ioFiller2; Ptr ioForeignPrivBuffer; long ioForeignPrivActCount; long ioForeignPrivReqCount; long ioFiller3; long ioForeignPrivDirID; long ioForeignPrivInfo1; long ioForeignPrivInfo2; long ioForeignPrivInfo3; long ioForeignPrivInfo4; }; typedef struct ForeignPrivParam ForeignPrivParam; typedef ForeignPrivParam *ForeignPrivParamPtr; æC æKY HParamBlockRec HParmBlkPtr æFc Files.h æT struct æD union HParamBlockRec { HIOParam ioParam; HFileParam fileParam; HVolumeParam volumeParam; AccessParam accessParam; ObjParam objParam; CopyParam copyParam; WDParam wdParam; FIDParam fidParam; CSParam csParam; ForeignPrivParam foreignPrivParam; }; typedef union HParamBlockRec HParamBlockRec; typedef HParamBlockRec *HParmBlkPtr; æC »FileParam Variant ( ParamBlockRec and HParamBlockRec) The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with one exception: The field ioDirID in HParamBlockRec is called ioFlNum in ParamBlockRec. The fields of the fileParam variant of HParamBlockRec are as follows: •••Refer to Technical Note #204:••• fileParam: (ioFRefNum: INTEGER; {path reference number} ioFVersNum: SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} ioFlVersNum: SignedByte; {version number} ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LONGINT; {directory ID or file number} ioFlStBlk: INTEGER; {first allocation block of data fork} ioFlLgLen: LONGINT; {logical end-of-file of data fork} ioFlPyLen: LONGINT; {physical end-of-file of data fork} ioFlRStBlk: INTEGER; {first allocation block of resource fork} ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} ioFlCrDat: LONGINT; {date and time of creation} ioFlMdDat: LONGINT); {date and time of last modification} IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the files in a given directory. Warning: When used with GetFileInfo, ioFDirIndex will index only the files in a directory. To index both files and directories, you can use ioFDirIndex with PBGetCatInfo. IOFlAttrib contains the following file attributes: Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open When passed to a routine, ioDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) When returned from a routine, ioDirID contains the file number of a file; most programmers needn’t be concerned with file numbers, but those interested can read the section “Data Organization on Volumes”. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty, respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat and ioFlMdDat fields are specified in seconds since midnight, January 1, 1904. »VolumeParam Variant (ParamBlockRec) When you call GetVolInfo, you’ll use the volumeParam variant of ParamBlockRec: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsBkUp: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVDirSt: INTEGER; {first block of directory} ioVBlLn: INTEGER; {length of directory in blocks} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtFNum: LONGINT; {next unused file number} ioVFrBlk: INTEGER); {number of unused allocation blocks} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsBkUp contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: The name ioVLsBkUp is actually a misnomer; this field has always contained the date and time of the last modification to the volume, not the last backup. Most programmers needn’t be concerned with the remaining parameters, but interested programmers can read the section “Data Organization on Volumes”. »VolumeParam Variant (HParamBlockRec) When you call HGetVInfo and SetVolInfo, you’ll use the volumeParam variant of HParamBlockRec. This is a superset of the volumeParam variant of ParamBlockRec; the names and functions of certain fields have been changed, and new fields have been added: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsMod: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVBitMap: INTEGER; {first block of volume bit map} ioAllocPtr: INTEGER; {block at which next new file starts} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtCNID: LONGINT; {next unused file number} ioVFrBlk: INTEGER; {number of unused allocation blocks} ioVSigWord: INTEGER; {volume signature} ioVDrvInfo: INTEGER; {drive number} ioVDRefNum: INTEGER; {driver reference number} ioVFSID: INTEGER; {file system handling this volume} ioVBkUp: LONGINT; {date and time of last backup} ioVSeqNum: INTEGER; {used internally} ioVWrCnt LONGINT; {volume write count} ioVFilCnt: LONGINT; {number of files on volume} ioVDirCnt: LONGINT; {number of directories on volume} ioVFndrInfo: ARRAY[1..8] OF LONGINT); {information used by the Finder} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsMod contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: IOVLsMod replaces the field ioVLsBkUp in ParamBlockRec. The name ioVLsBkUp was actually a misnomer; this field has always contained the date and time of the last modification, not the last backup. Another field, ioVBkUp, contains the date and time of the last backup. IOVClpSiz can be used to set the volume clump size in bytes; it’s used for files that don’t have a clump size defined as part of their file information in the catalog. To promote file contiguity and avoid fragmentation, space is allocated to a file not in allocation blocks but in clumps. A clump is a group of contiguous allocation blocks. The clump size is always a multiple of the allocation block size; it’s the minimum number of bytes to allocate each time the Allocate function is called or the end-of-file is reached during the Write routine. IOVSigWord contains a signature word identifying the type of volume; it’s $D2D7 for flat directory volumes and $4244 for hierarchical directory volumes. The drive number of the drive containing the volume is returned in ioDrvInfo. For on-line volumes, ioVDRefNum returns the reference number of the I/O driver for the drive identified by ioDrvInfo. IOVFSID is the file-system identifier. It indicates which file system is servicing the volume; it’s 0 for File Manager volumes and nonzero for volumes handled by an external file system. IOVBkUp specifies the date and time the volume was last backed up (it’s 0 if never backed up). IOVNmFls contains the number of files in the root directory. IOVFilCnt contains the total number of files on the volume, while ioVDirCnt contains the total number of directories (not including the root directory). Most programmers needn’t be concerned with the other parameters, but interested programmers can read the section “Data Organization on Volumes”. HParamBlockRec, described above, has been extended to support a shared environment with the addition of AccessParam, ObjParam, CopyParam, and WDParam, as shown below. (The complete HParamBlockRec data type is shown in the summary.) AccessParam: (filler3: INTEGER; ioDenyModes: INTEGER; {access rights data} filler4: INTEGER; filler5: Signed Byte; ioACUser: Signed Byte; {access rights for directory only} filler6: LONGINT; ioACOwnerID: LONGINT; {owner ID} ioACGroupID: LONGINT; {group ID} ioACAccess: LONGINT); {access rights} ObjParam: (filler7: INTEGER; ioObjType: INTEGER; {function code} ioObjNamePtr: Ptr; {ptr to returned creator/group name} ioObjID: LONGINT; {creator/group ID} ioReqCount: LONGINT; {size of buffer area} ioActCount: LONGINT); {length of vol parms data} CopyParam: (ioDstVRefNum: INTEGER; {destination vol identifier} filler8: INTEGER; ioNewName: Ptr; {ptr to destination pathname} ioCopyName: Ptr; {ptr to optional name} ioNewDirID: LONGINT); {destination directory ID} WDParam: (filler9: INTEGER; ioWDIndex: INTEGER; ioWDProcID: LONGINT; ioWDVRefNum: INTEGER; filler10: INTEGER; filler11: LONGINT; filler12: LONGINT; filler13: LONGINT; ioWDDirID: LONGINT); æKY CMovePBRec CMovePBPtr æFc Files.h æT struct æD struct CMovePBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; ProcPtr ioCompletion; OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; long filler1; StringPtr ioNewName; long filler2; long ioNewDirID; long filler3[2]; long ioDirID; }; typedef struct CMovePBRec CMovePBRec; typedef CMovePBRec *CMovePBPtr; æC »CMovePBRec When you call CatMove to move files or directories into a different directory, you’ll use the following six additional fields after the standard eight fields in the parameter block record CMovePBRec: filler1: LONGINT; {not used} ioNewName: StringPtr; {name of new directory} filler2: LONGINT; {not used} ioNewDirID: LONGINT; {directory ID of new directory} filler3: ARRAY[1..2] OF LONGINT; {not used} ioDirID: LONGINT); {directory ID of current directory} IONewName and ioNewDirID specify the name and directory ID of the directory to which the file or directory is to be moved. IODirID (used in conjuntion with the ioVRefNum and ioNamePtr) specifies the current directory ID of the file or directory to be moved. æKY WDPBRec WDPBPtr æFc Files.h æT struct æD struct WDPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; ProcPtr ioCompletion; OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short filler1; short ioWDIndex; long ioWDProcID; short ioWDVRefNum; short filler2[7]; long ioWDDirID; }; typedef struct WDPBRec WDPBRec; typedef WDPBRec *WDPBPtr; æC »WDPBRec When you call the routines that open, close, and get information about working directories, you’ll use the following six additional fields after the standard eight fields in the parameter block record WDPBRec: filler1: INTEGER; {not used} ioWDIndex: INTEGER; {index} ioWDProcID: LONGINT; {working directory user identifier} ioWDVRefNum: INTEGER; {working directory's volume reference number} filler2: ARRAY[1..7] OF INTEGER; {not used} ioWDDirID: LONGINT); {working directory's directory ID} IOWDIndex can be used with the function PBGetWDInfo to index through the current working directories. IOWDProcID is an identifier that’s used to distinguish between working directories set up by different users; you should use the application’s signature (discussed in the Finder Interface chapter) as the ioWDProcID. æKY FCBPBRec FCBPBPtr æFc Files.h æT struct æD struct FCBPBRec { QElemPtr qLink; short qType; short ioTrap; Ptr ioCmdAddr; ProcPtr ioCompletion; OSErr ioResult; StringPtr ioNamePtr; short ioVRefNum; short ioRefNum; short filler; short ioFCBIndx; short filler1; long ioFCBFlNm; short ioFCBFlags; unsigned short ioFCBStBlk; long ioFCBEOF; long ioFCBPLen; long ioFCBCrPs; short ioFCBVRefNum; long ioFCBClpSiz; long ioFCBParID; }; typedef struct FCBPBRec FCBPBRec; typedef FCBPBRec *FCBPBPtr; æC æKY VCB æFc Files.h æT struct æD struct VCB { QElemPtr qLink; short qType; short vcbFlags; unsigned short vcbSigWord; unsigned long vcbCrDate; unsigned long vcbLsMod; short vcbAtrb; unsigned short vcbNmFls; short vcbVBMSt; short vcbAllocPtr; unsigned short vcbNmAlBlks; long vcbAlBlkSiz; long vcbClpSiz; short vcbAlBlSt; long vcbNxtCNID; unsigned short vcbFreeBks; Str27 vcbVN; short vcbDrvNum; short vcbDRefNum; short vcbFSID; short vcbVRefNum; Ptr vcbMAdr; Ptr vcbBufAdr; short vcbMLen; short vcbDirIndex; short vcbDirBlk; unsigned long vcbVolBkUp; unsigned short vcbVSeqNum; long vcbWrCnt; long vcbXTClpSiz; long vcbCTClpSiz; unsigned short vcbNmRtDirs; long vcbFilCnt; long vcbDirCnt; long vcbFndrInfo[8]; unsigned short vcbVCSize; unsigned short vcbVBMCSiz; unsigned short vcbCtlCSiz; unsigned short vcbXTAlBlks; unsigned short vcbCTAlBlks; short vcbXTRef; short vcbCTRef; Ptr vcbCtlBuf; long vcbDirIDM; short vcbOffsM; }; typedef struct VCB VCB; æC »Volume Control Blocks •••Refer to Technical Note #106:••• Each time a volume is mounted, its volume information is read from it and is used to build a new volume control block in the volume-control-block queue (unless an ejected or off-line volume is being remounted). A copy of the volume block map is also read from the volume and placed in the system heap, and a volume buffer is created in the system heap. The volume-control-block queue is a standard Operating System queue that’s maintained in the system heap. It contains a volume control block for each mounted volume. A volume control block is a 178-byte nonrelocatable block that contains volume-specific information. It has the following structure: TYPE VCB = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} vcbFlags: INTEGER; {bit 15=1 if dirty} vcbSigWord: INTEGER; {$4244 for hierarchical, $D2D7 for flat} vcbCrDate: LONGINT; {date and time of initialization} vcbLsMod: LONGINT; {date and time of last modification} vcbAtrb: INTEGER; {volume attributes} vcbNmFls: INTEGER; {number of files in directory} vcbVBMSt: INTEGER; {first block of volume bit map} vcbAllocPtr: INTEGER; {used internally} vcbNmAlBlks: INTEGER; {number of allocation blocks} vcbAlBlkSiz: LONGINT; {allocation block size} vcbClpSiz: LONGINT; {default clump size} vcbAlBlSt: INTEGER; {first block in block map} vcbNxtCNID: LONGINT; {next unused directory ID or file number} vcbFreeBks: INTEGER; {number of unused allocation blocks} vcbVN: STRING[27]; {volume name} vcbDrvNum: INTEGER; {drive number} vcbDRefNum: INTEGER; {driver reference number} vcbFSID: INTEGER; {file-system identifier} vcbVRefNum: INTEGER; {volume reference number} vcbMAdr: Ptr; {pointer to block map} vcbBufAdr: Ptr; {pointer to volume buffer} vcbMLen: INTEGER; {number of bytes in block map} vcbDirIndex: INTEGER; {used internally} vcbDirBlk: INTEGER; {used internally} vcbVolBkUp: LONGINT; {date and time of last backup} vcbVSeqNum: INTEGER; {used internally} vcbWrCnt: LONGINT; {volume write count} vcbXTClpSiz: LONGINT; {clump size of extents tree file} vcbCTClpSiz: LONGINT; {clump size of catalog tree file} vcbNmRtDirs: INTEGER; {number of directories in root} vcbFilCnt: LONGINT; {number of files on volume} vcbDirCnt: LONGINT; {number of directories on volume} vcbFndrInfo: ARRAY[1..8] OF LONGINT; {information used by } { the Finder} vcbVCSize: INTEGER; {used internally} vcbVBMCSiz: INTEGER; {used internally} vcbCtlCSiz: INTEGER; {used internally} vcbXTAlBks: INTEGER; {size in blocks of extents tree file} vcbCTAlBks: INTEGER; {size in blocks of catalog tree file} vcbXTRef: INTEGER; {path reference number for extents } { tree file} vcbCTRef: INTEGER; {path reference number for catalog } { tree file} vcbCtlBuf: Ptr; {pointer to extents and catalog } { tree caches} vcbDirIDM: LONGINT; {directory last searched} vcbOffsM: INTEGER {offspring index at last search} END; 64K ROM note: A volume control block created for a flat volume is a subset of the above structure. It’s actually smaller and contains only the fields up to and including vcbDirBlk. In addition, the names of several fields have been changed to reflect the fact that they contain different information on hierarchical volumes: vcbLsBkUp, vcbDirSt, vcbBlLn, vcbNmBlks, and vcbNxtFNum have been changed to vcbLsMod, vcbVBMSt, vcbAllocPtr, vcbNmAlBlks, and vcbNxtCNID respectively. QLink points to the next entry in the queue, and qType indicates the queue type, which must always be ORD(fsQType). Bit 15 of vcbFlags is set if the volume information has been changed by a routine call since the volume was last affected by a FlushVol call. VCBLsMod contains the date and time that the volume was last modified (this is not necessarily when it was flushed). 64K ROM note: VCBLsMod replaces the field vcbLsBkUp from flat directory volumes. The name vcbLsBkUp was actually a misnomer; this field has always contained the date and time of the last modification, not the last backup. Another field, vcbVolBkUp, contains the date and time of the last backup. VCBAtrb contains the volume attributes, as follows: Bit Meaning 0–4 Set if inconsistencies were found between the volume information and the file directory when the volume was mounted 6 Set if volume is busy (one or more files are open) 7 Set if volume is locked by hardware 15 Set if volume is locked by software VCBVBMSt contains the number of the first block in the volume bit map; on flat volumes, it contains the first block of the file directory. VCBNmAlBlks contains the number of allocation blocks on the volume, and vcbFreeBks specifies how many of those blocks are unused. VCBAlBlSt is used only with flat volumes; it contains the number of the first block in the block map. VCBDrvNum contains the drive number of the drive on which the volume is mounted; vcbDRefNum contains the driver reference number of the driver used to access the volume. When a mounted volume is placed off-line, vcbDrvNum is cleared. When a volume is ejected, vcbDrvNum is cleared and vcbDRefNum is set to the negative of vcbDrvNum (becoming a positive number). VCBFSID identifies the file system handling the volume; it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled by other file systems. When a volume is placed off-line, its buffer and bit map (or block map, in the case of flat directory volumes) are released. When a volume is unmounted, its volume control block is removed from the volume-control-block queue. You can get a pointer to the header of the volume-control-block queue by calling the File Manager function GetVCBQHdr. æKY DrvQEl DrvQElPtr æFc Files.h æT struct æD struct DrvQEl { QElemPtr qLink; short qType; short dQDrive; short dQRefNum; short dQFSID; unsigned short dQDrvSz; unsigned short dQDrvSz2; }; typedef struct DrvQEl DrvQEl; typedef DrvQEl *DrvQElPtr; æC »The Drive Queue •••Refer to Technical Note #36:••• Disk drives connected to the Macintosh are opened when the system starts up, and information describing each is placed in the drive queue. This is a standard Operating System queue, and each entry in it has the following structure: TYPE DrvQEl = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} dQDrive: INTEGER; {drive number} dQRefNum: INTEGER; {driver reference number} dQFSID: INTEGER; {file-system identifier} dQDrvSz: INTEGER; {number of logical blocks on drive} dQDrvSz2: INTEGER; {additional field to handle large } { drive size} END; QLink points to the next entry in the queue. If qType is 0, this means the number of logical blocks on the drive is contained in the dQDrvSz field alone. If qType is 1, both dQDrvSz and dQDrvSz2 are used to store the number of blocks; dqDrvSz2 contains the high-order word of this number and dQDrvSz contains the low-order word. DQDrive contains the drive number of the drive on which the volume is mounted; dQRefNum contains the driver reference number of the driver controlling the device on which the volume is mounted. DQFSID identifies the file system handling the volume in the drive; it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled by other file systems. Four bytes of flags precede each drive queue entry; they’re accessible only from assembly language. Assembly-language note: These bytes contain the following: Byte Contents 0 Bit 7=1 if volume is locked 1 0 if no disk in drive; 1 or 2 if disk in drive; 8 if nonejectable disk in drive; $FC-$FF if disk was ejected within last 1.5 seconds; $48 if disk in drive is nonejectable but driver wants a call 2 Used internally during system startup 3 Bit 7=0 if disk is single-sided You can get a pointer to the header of the drive queue by calling the File Manager function GetDrvQHdr. æKY NumVersion æFc Files.h æT struct æD struct NumVersion { unsigned char majorRev; /*1st part of version number in BCD*/ unsigned int minorRev : 4; /*2nd part is 1 nibble in BCD*/ unsigned int bugFixRev : 4; /*3rd part is 1 nibble in BCD*/ unsigned char stage; /*stage code: dev, alpha, beta, final*/ unsigned char nonRelRev; /*revision level of non-released version*/ }; typedef struct NumVersion NumVersion; æC æKY VersRec VersRecPtr VersRecHndl æFc Files.h æT struct æD struct VersRec { NumVersion numericVersion; /*encoded version number*/ short countryCode; /*country code from intl utilities*/ Str255 shortVersion; /*version number string - worst case*/ Str255 reserved; /*longMessage string packed after shortVersion*/ }; typedef struct VersRec VersRec; typedef VersRec *VersRecPtr, **VersRecHndl; æC æKY PBOpen æFc Files.h æT Function æD pascal OSErr PBOpen(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBOpen((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-108 æC Trap macro _Open Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpen creates an access path to the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. A path reference number is returned in ioRefNum. IOMisc either points to a portion of memory (522 bytes) to be used as the access path’s buffer, or is NIL if you want the volume buffer to be used instead. Warning: All access paths to a single file that’s opened multiple times should share the same buffer so that they will read and write the same data. IOPermssn specifies the path’s read/write permission. A path can be opened for writing even if it accesses a file on a locked volume, and an error won’t be returned until a PBWrite, PBSetEOF, or PBAllocate call is made. If you attempt to open a locked file for writing, PBOpen will return permErr as its function result. If you request exclusive read/write permission but another access path already has write permission (whether write only, exclusive read/write, or shared read/write), PBOpen will return the reference number of the existing access path in ioRefNum and opWrErr as its function result. Similarly, if you request shared read/write permission but another access path already has exclusive read/write permission, PBOpen will return the reference number of the access path in ioRefNum and opWrErr as its function result. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenSync æFc Files.h æT Function æTN A000 æD #pragma parameter __D0 PBOpenSync(__A0) pascal OSErr PBOpenSync(ParmBlkPtr paramBlock) = 0xA000; æDT #pragma parameter __D0 myVariable = PBOpenSync()(__A0); æRI II-108 æC Trap macro _Open Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpen creates an access path to the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. A path reference number is returned in ioRefNum. IOMisc either points to a portion of memory (522 bytes) to be used as the access path’s buffer, or is NIL if you want the volume buffer to be used instead. Warning: All access paths to a single file that’s opened multiple times should share the same buffer so that they will read and write the same data. IOPermssn specifies the path’s read/write permission. A path can be opened for writing even if it accesses a file on a locked volume, and an error won’t be returned until a PBWrite, PBSetEOF, or PBAllocate call is made. If you attempt to open a locked file for writing, PBOpen will return permErr as its function result. If you request exclusive read/write permission but another access path already has write permission (whether write only, exclusive read/write, or shared read/write), PBOpen will return the reference number of the existing access path in ioRefNum and opWrErr as its function result. Similarly, if you request shared read/write permission but another access path already has exclusive read/write permission, PBOpen will return the reference number of the access path in ioRefNum and opWrErr as its function result. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenAsync æFc Files.h æT Function æTN A400 æD #pragma parameter __D0 PBOpenAsync(__A0) pascal OSErr PBOpenAsync(ParmBlkPtr paramBlock) = 0xA400; æDT #pragma parameter __D0 myVariable = PBOpenAsync()(__A0); æRI II-108 æC Trap macro _Open Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpen creates an access path to the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. A path reference number is returned in ioRefNum. IOMisc either points to a portion of memory (522 bytes) to be used as the access path’s buffer, or is NIL if you want the volume buffer to be used instead. Warning: All access paths to a single file that’s opened multiple times should share the same buffer so that they will read and write the same data. IOPermssn specifies the path’s read/write permission. A path can be opened for writing even if it accesses a file on a locked volume, and an error won’t be returned until a PBWrite, PBSetEOF, or PBAllocate call is made. If you attempt to open a locked file for writing, PBOpen will return permErr as its function result. If you request exclusive read/write permission but another access path already has write permission (whether write only, exclusive read/write, or shared read/write), PBOpen will return the reference number of the existing access path in ioRefNum and opWrErr as its function result. Similarly, if you request shared read/write permission but another access path already has exclusive read/write permission, PBOpen will return the reference number of the access path in ioRefNum and opWrErr as its function result. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBClose æFc Files.h æT Function æD pascal OSErr PBClose(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBClose((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-114 æC Trap macro _Close Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBClose writes the contents of the access path buffer specified by ioRefNum to the volume and removes the access path. Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBCloseSync æFc Files.h æT Function æTN A001 æD #pragma parameter __D0 PBCloseSync(__A0) pascal OSErr PBCloseSync(ParmBlkPtr paramBlock) = 0xA001; æDT #pragma parameter __D0 myVariable = PBCloseSync()(__A0); æRI II-114 æC Trap macro _Close Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBClose writes the contents of the access path buffer specified by ioRefNum to the volume and removes the access path. Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBCloseAsync æFc Files.h æT Function æTN A401 æD #pragma parameter __D0 PBCloseAsync(__A0) pascal OSErr PBCloseAsync(ParmBlkPtr paramBlock) = 0xA401; æDT #pragma parameter __D0 myVariable = PBCloseAsync()(__A0); æRI II-114 æC Trap macro _Close Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBClose writes the contents of the access path buffer specified by ioRefNum to the volume and removes the access path. Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBRead æFc Files.h æT Function æD pascal OSErr PBRead(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBRead((ParmBlkPtr) paramBlock,(Boolean) async); æRT 187 æRI II-110 æC Trap macro _Read Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBRead attempts to read ioReqCount bytes from the open file whose access path is specified by ioRefNum, and transfer them to the data buffer pointed to by ioBuffer. The position of the mark is specified by ioPosMode and ioPosOffset. If you try to read past the logical end-of-file, PBRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the mark is returned in ioPosOffset and the number of bytes actually read is returned in ioActCount. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBReadSync æFc Files.h æT Function æTN A002 æD #pragma parameter __D0 PBReadSync(__A0) pascal OSErr PBReadSync(ParmBlkPtr paramBlock) = 0xA002; æDT #pragma parameter __D0 myVariable = PBReadSync()(__A0); æRT 187 æRI II-110 æC Trap macro _Read Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBRead attempts to read ioReqCount bytes from the open file whose access path is specified by ioRefNum, and transfer them to the data buffer pointed to by ioBuffer. The position of the mark is specified by ioPosMode and ioPosOffset. If you try to read past the logical end-of-file, PBRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the mark is returned in ioPosOffset and the number of bytes actually read is returned in ioActCount. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBReadAsync æFc Files.h æT Function æTN A402 æD #pragma parameter __D0 PBReadAsync(__A0) pascal OSErr PBReadAsync(ParmBlkPtr paramBlock) = 0xA402; æDT #pragma parameter __D0 myVariable = PBReadAsync()(__A0); æRT 187 æRI II-110 æC Trap macro _Read Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBRead attempts to read ioReqCount bytes from the open file whose access path is specified by ioRefNum, and transfer them to the data buffer pointed to by ioBuffer. The position of the mark is specified by ioPosMode and ioPosOffset. If you try to read past the logical end-of-file, PBRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the mark is returned in ioPosOffset and the number of bytes actually read is returned in ioActCount. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBWrite æFc Files.h æT Function æD pascal OSErr PBWrite(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBWrite((ParmBlkPtr) paramBlock,(Boolean) async); æRT 187 æRI II-110 æC •••Refer to Technical Note #187:••• Trap macro _Write Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. After the write is completed, the mark is returned in ioPosOffset and the number of bytes actually written is returned in ioActCount. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount posErr Attempt to position before start of file rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBWriteSync æFc Files.h æT Function æTN A003 æD #pragma parameter __D0 PBWriteSync(__A0) pascal OSErr PBWriteSync(ParmBlkPtr paramBlock) = 0xA003; æDT #pragma parameter __D0 myVariable = PBWriteSync()(__A0); æRT 187 æRI II-110 æC •••Refer to Technical Note #187:••• Trap macro _Write Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. After the write is completed, the mark is returned in ioPosOffset and the number of bytes actually written is returned in ioActCount. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount posErr Attempt to position before start of file rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBWriteAsync æFc Files.h æT Function æTN A403 æD #pragma parameter __D0 PBWriteAsync(__A0) pascal OSErr PBWriteAsync(ParmBlkPtr paramBlock) = 0xA403; æDT #pragma parameter __D0 myVariable = PBWriteAsync()(__A0); æRT 187 æRI II-110 æC •••Refer to Technical Note #187:••• Trap macro _Write Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. After the write is completed, the mark is returned in ioPosOffset and the number of bytes actually written is returned in ioActCount. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount posErr Attempt to position before start of file rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBGetVInfo æFc Files.h æT Function æD pascal OSErr PBGetVInfo(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetVInfo((ParmBlkPtr) paramBlock,(Boolean) async); æRT 24, 44, 157 æRI II-104, IV-129, N24-1, N44-2, N157 æC Trap macro _GetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsBkUp long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVDirSt word <-- 44 ioVBlLn word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word PBGetVInfo returns information about the specified volume. If ioVolIndex is positive, the File Manager attempts to use it to find the volume; for instance, if ioVolIndex is 2, the File Manager will attempt to access the second mounted volume. If ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way (described in the section “Specifying Volumes, Directories, and Files”) to determine which volume. If ioVolIndex is 0, the File Manager attempts to access the volume by using ioVRefNum only. The volume reference number is returned in ioVRefNum, and a pointer to the volume name is returned in ioNamePtr (unless ioNamePtr is NIL). If a working directory reference number is passed in ioVRefNum (or if the default directory is a subdirectory), the number of files and directories in the specified directory (the directory’s valence) will be returned in ioVNmFls. Also, the volume reference number won’t be returned; ioVRefNum will still contain the working directory reference number. Warning: IOVNmAlBlks and ioVFrBlks, which are actually unsigned integers, are clipped to 31744 ($7C00) regardless of the size of the volume. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBGetVInfoSync æFc Files.h æT Function æTN A007 æD #pragma parameter __D0 PBGetVInfoSync(__A0) pascal OSErr PBGetVInfoSync(ParmBlkPtr paramBlock) = 0xA007; æDT #pragma parameter __D0 myVariable = PBGetVInfoSync()(__A0); æRT 24, 44, 157 æRI II-104, IV-129, N24-1, N44-2, N157 æC Trap macro _GetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsBkUp long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVDirSt word <-- 44 ioVBlLn word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word PBGetVInfo returns information about the specified volume. If ioVolIndex is positive, the File Manager attempts to use it to find the volume; for instance, if ioVolIndex is 2, the File Manager will attempt to access the second mounted volume. If ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way (described in the section “Specifying Volumes, Directories, and Files”) to determine which volume. If ioVolIndex is 0, the File Manager attempts to access the volume by using ioVRefNum only. The volume reference number is returned in ioVRefNum, and a pointer to the volume name is returned in ioNamePtr (unless ioNamePtr is NIL). If a working directory reference number is passed in ioVRefNum (or if the default directory is a subdirectory), the number of files and directories in the specified directory (the directory’s valence) will be returned in ioVNmFls. Also, the volume reference number won’t be returned; ioVRefNum will still contain the working directory reference number. Warning: IOVNmAlBlks and ioVFrBlks, which are actually unsigned integers, are clipped to 31744 ($7C00) regardless of the size of the volume. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBGetVInfoAsync æFc Files.h æT Function æTN A407 æD #pragma parameter __D0 PBGetVInfoAsync(__A0) pascal OSErr PBGetVInfoAsync(ParmBlkPtr paramBlock) = 0xA407; æDT #pragma parameter __D0 myVariable = PBGetVInfoAsync()(__A0); æRT 24, 44, 157 æRI II-104, IV-129, N24-1, N44-2, N157 æC Trap macro _GetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsBkUp long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVDirSt word <-- 44 ioVBlLn word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word PBGetVInfo returns information about the specified volume. If ioVolIndex is positive, the File Manager attempts to use it to find the volume; for instance, if ioVolIndex is 2, the File Manager will attempt to access the second mounted volume. If ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way (described in the section “Specifying Volumes, Directories, and Files”) to determine which volume. If ioVolIndex is 0, the File Manager attempts to access the volume by using ioVRefNum only. The volume reference number is returned in ioVRefNum, and a pointer to the volume name is returned in ioNamePtr (unless ioNamePtr is NIL). If a working directory reference number is passed in ioVRefNum (or if the default directory is a subdirectory), the number of files and directories in the specified directory (the directory’s valence) will be returned in ioVNmFls. Also, the volume reference number won’t be returned; ioVRefNum will still contain the working directory reference number. Warning: IOVNmAlBlks and ioVFrBlks, which are actually unsigned integers, are clipped to 31744 ($7C00) regardless of the size of the volume. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBGetVol æFc Files.h æT Function æD pascal OSErr PBGetVol(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetVol((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-104, IV-131 æC Trap macro _GetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word PBGetVol returns a pointer to the name of the default volume in ioNamePtr (unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a default directory was set with a previous PBSetVol call, a pointer to its name will be returned in ioNamePtr and its working directory reference number in ioVRefNum. Result codes noErr No error nsvErr No default volume æKY PBGetVolSync æFc Files.h æT Function æTN A014 æD #pragma parameter __D0 PBGetVolSync(__A0) pascal OSErr PBGetVolSync(ParmBlkPtr paramBlock) = 0xA014; æDT #pragma parameter __D0 myVariable = PBGetVolSync()(__A0); æRI II-104, IV-131 æC Trap macro _GetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word PBGetVol returns a pointer to the name of the default volume in ioNamePtr (unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a default directory was set with a previous PBSetVol call, a pointer to its name will be returned in ioNamePtr and its working directory reference number in ioVRefNum. Result codes noErr No error nsvErr No default volume æKY PBGetVolAsync æFc Files.h æT Function æTN A414 æD #pragma parameter __D0 PBGetVolAsync(__A0) pascal OSErr PBGetVolAsync(ParmBlkPtr paramBlock) = 0xA414; æDT #pragma parameter __D0 myVariable = PBGetVolAsync()(__A0); æRI II-104, IV-131 æC Trap macro _GetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word PBGetVol returns a pointer to the name of the default volume in ioNamePtr (unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a default directory was set with a previous PBSetVol call, a pointer to its name will be returned in ioNamePtr and its working directory reference number in ioVRefNum. Result codes noErr No error nsvErr No default volume æKY PBSetVol æFc Files.h æT Function æD pascal OSErr PBSetVol(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetVol((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-105, IV-132 æC Trap macro _SetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the default directory. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY PBSetVolSync æFc Files.h æT Function æTN A015 æD #pragma parameter __D0 PBSetVolSync(__A0) pascal OSErr PBSetVolSync(ParmBlkPtr paramBlock) = 0xA015; æDT #pragma parameter __D0 myVariable = PBSetVolSync()(__A0); æRI II-105, IV-132 æC Trap macro _SetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the default directory. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY PBSetVolAsync æFc Files.h æT Function æTN A415 æD #pragma parameter __D0 PBSetVolAsync(__A0) pascal OSErr PBSetVolAsync(ParmBlkPtr paramBlock) = 0xA415; æDT #pragma parameter __D0 myVariable = PBSetVolAsync()(__A0); æRI II-105, IV-132 æC Trap macro _SetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the default directory. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY PBFlushVol æFc Files.h æT Function æD pascal OSErr PBFlushVol(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBFlushVol((ParmBlkPtr) paramBlock,(Boolean) async); æMM æRI II-105, IV-133 æC Trap macro _FlushVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVol was called). Note: The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBFlushVolSync æFc Files.h æT Function æTN A013 æD #pragma parameter __D0 PBFlushVolSync(__A0) pascal OSErr PBFlushVolSync(ParmBlkPtr paramBlock) = 0xA013; æDT #pragma parameter __D0 myVariable = PBFlushVolSync()(__A0); æMM æRI II-105, IV-133 æC Trap macro _FlushVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVol was called). Note: The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBFlushVolAsync æFc Files.h æT Function æTN A413 æD #pragma parameter __D0 PBFlushVolAsync(__A0) pascal OSErr PBFlushVolAsync(ParmBlkPtr paramBlock) = 0xA413; æDT #pragma parameter __D0 myVariable = PBFlushVolAsync()(__A0); æMM æRI II-105, IV-133 æC Trap macro _FlushVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVol was called). Note: The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBCreate æFc Files.h æT Function æD pascal OSErr PBCreate(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBCreate((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-107, IV-145 æC Trap macro _Create Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the application terminates), the application should call PBSetFInfo (after PBCreate) to fill in the information needed by the Finder. Assembly-language note: If a desk accessory creates a file, it should always create it in the directory containing the system folder. The working directory reference number for this directory is stored in the global variable BootDrive; you can pass it in ioVRefNum. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBCreateSync æFc Files.h æT Function æTN A008 æD #pragma parameter __D0 PBCreateSync(__A0) pascal OSErr PBCreateSync(ParmBlkPtr paramBlock) = 0xA008; æDT #pragma parameter __D0 myVariable = PBCreateSync()(__A0); æRI II-107, IV-145 æC Trap macro _Create Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the application terminates), the application should call PBSetFInfo (after PBCreate) to fill in the information needed by the Finder. Assembly-language note: If a desk accessory creates a file, it should always create it in the directory containing the system folder. The working directory reference number for this directory is stored in the global variable BootDrive; you can pass it in ioVRefNum. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBCreateAsync æFc Files.h æT Function æTN A408 æD #pragma parameter __D0 PBCreateAsync(__A0) pascal OSErr PBCreateAsync(ParmBlkPtr paramBlock) = 0xA408; æDT #pragma parameter __D0 myVariable = PBCreateAsync()(__A0); æRI II-107, IV-145 æC Trap macro _Create Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the application terminates), the application should call PBSetFInfo (after PBCreate) to fill in the information needed by the Finder. Assembly-language note: If a desk accessory creates a file, it should always create it in the directory containing the system folder. The working directory reference number for this directory is stored in the global variable BootDrive; you can pass it in ioVRefNum. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDelete æFc Files.h æT Function æD pascal OSErr PBDelete(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBDelete((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-119, IV-147 æC Trap macro _Delete Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBDelete removes the closed file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) from the volume pointed to by ioVRefNum. PBHDelete can be used to delete an empty directory as well. Note: This function will delete both forks of the file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy, directory not empty, or working directory control block open fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDeleteSync æFc Files.h æT Function æTN A009 æD #pragma parameter __D0 PBDeleteSync(__A0) pascal OSErr PBDeleteSync(ParmBlkPtr paramBlock) = 0xA009; æDT #pragma parameter __D0 myVariable = PBDeleteSync()(__A0); æRI II-119, IV-147 æC Trap macro _Delete Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBDelete removes the closed file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) from the volume pointed to by ioVRefNum. PBHDelete can be used to delete an empty directory as well. Note: This function will delete both forks of the file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy, directory not empty, or working directory control block open fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDeleteAsync æFc Files.h æT Function æTN A409 æD #pragma parameter __D0 PBDeleteAsync(__A0) pascal OSErr PBDeleteAsync(ParmBlkPtr paramBlock) = 0xA409; æDT #pragma parameter __D0 myVariable = PBDeleteAsync()(__A0); æRI II-119, IV-147 æC Trap macro _Delete Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBDelete removes the closed file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) from the volume pointed to by ioVRefNum. PBHDelete can be used to delete an empty directory as well. Note: This function will delete both forks of the file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy, directory not empty, or working directory control block open fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBOpenDF æFc Files.h æT Function æD pascal OSErr PBOpenDF(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBOpenDF((ParmBlkPtr) paramBlock,(Boolean) async); æRI PBOpenWD function IV-158, N77-1 æC æKY PBOpenDFSync æFc Files.h æT Function æTN 701A,A060 æD #pragma parameter __D0 PBOpenDFSync(__A0) pascal OSErr PBOpenDFSync(ParmBlkPtr paramBlock) = {0x701A,0xA060}; æDT #pragma parameter __D0 myVariable = PBOpenDFSync()(__A0); æRI PBOpenWD function IV-158, N77-1 æC æKY PBOpenDFAsync æFc Files.h æT Function æTN 701A,A460 æD #pragma parameter __D0 PBOpenDFAsync(__A0) pascal OSErr PBOpenDFAsync(ParmBlkPtr paramBlock) = {0x701A,0xA460}; æDT #pragma parameter __D0 myVariable = PBOpenDFAsync()(__A0); æRI PBOpenWD function IV-158, N77-1 æC æKY PBOpenRF æFc Files.h æT Function æD pascal OSErr PBOpenRF(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBOpenRF((ParmBlkPtr) paramBlock,(Boolean) async); æMM æRT 74 æRI II-109, IV-137 æC Trap macro _OpenRF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpenRF is identical to PBOpen, except that it opens the file’s resource fork instead of its data fork. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. PBOpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenRFSync æFc Files.h æT Function æTN A00A æD #pragma parameter __D0 PBOpenRFSync(__A0) pascal OSErr PBOpenRFSync(ParmBlkPtr paramBlock) = 0xA00A; æDT #pragma parameter __D0 myVariable = PBOpenRFSync()(__A0); æMM æRT 74 æRI II-109, IV-137 æC Trap macro _OpenRF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpenRF is identical to PBOpen, except that it opens the file’s resource fork instead of its data fork. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. PBOpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenRFAsync æFc Files.h æT Function æTN A40A æD #pragma parameter __D0 PBOpenRFAsync(__A0) pascal OSErr PBOpenRFAsync(ParmBlkPtr paramBlock) = 0xA40A; æDT #pragma parameter __D0 myVariable = PBOpenRFAsync()(__A0); æMM æRT 74 æRI II-109, IV-137 æC Trap macro _OpenRF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpenRF is identical to PBOpen, except that it opens the file’s resource fork instead of its data fork. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. PBOpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBRename æFc Files.h æT Function æD pascal OSErr PBRename(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBRename((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-118, IV-153 æC Trap macro _Rename Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc pointer Given a pointer to a file name in ioNamePtr (and on flat volumes, a version number in ioVersNum), PBRename changes the name of the file to the name pointed to by ioMisc. (If the name pointed to by ioNamePtr contains one or more colons, so must the name pointed to by ioMisc.) Access paths currently in use aren’t affected. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the volume to the name pointed to by ioMisc. If a volume to be renamed is specified by its volume reference number, ioNamePtr can be NIL. Warning: If a volume to be renamed is specified by its volume name, be sure that it ends with a colon, or Rename will consider it a file name. Result codes noErr No error bdNamErr Bad file name dirFulErr File directory full dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRenameSync æFc Files.h æT Function æTN A00B æD #pragma parameter __D0 PBRenameSync(__A0) pascal OSErr PBRenameSync(ParmBlkPtr paramBlock) = 0xA00B; æDT #pragma parameter __D0 myVariable = PBRenameSync()(__A0); æRI II-118, IV-153 æC Trap macro _Rename Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc pointer Given a pointer to a file name in ioNamePtr (and on flat volumes, a version number in ioVersNum), PBRename changes the name of the file to the name pointed to by ioMisc. (If the name pointed to by ioNamePtr contains one or more colons, so must the name pointed to by ioMisc.) Access paths currently in use aren’t affected. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the volume to the name pointed to by ioMisc. If a volume to be renamed is specified by its volume reference number, ioNamePtr can be NIL. Warning: If a volume to be renamed is specified by its volume name, be sure that it ends with a colon, or Rename will consider it a file name. Result codes noErr No error bdNamErr Bad file name dirFulErr File directory full dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRenameAsync æFc Files.h æT Function æTN A40B æD #pragma parameter __D0 PBRenameAsync(__A0) pascal OSErr PBRenameAsync(ParmBlkPtr paramBlock) = 0xA40B; æDT #pragma parameter __D0 myVariable = PBRenameAsync()(__A0); æRI II-118, IV-153 æC Trap macro _Rename Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc pointer Given a pointer to a file name in ioNamePtr (and on flat volumes, a version number in ioVersNum), PBRename changes the name of the file to the name pointed to by ioMisc. (If the name pointed to by ioNamePtr contains one or more colons, so must the name pointed to by ioMisc.) Access paths currently in use aren’t affected. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the volume to the name pointed to by ioMisc. If a volume to be renamed is specified by its volume reference number, ioNamePtr can be NIL. Warning: If a volume to be renamed is specified by its volume name, be sure that it ends with a colon, or Rename will consider it a file name. Result codes noErr No error bdNamErr Bad file name dirFulErr File directory full dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBGetFInfo æFc Files.h æT Function æD pascal OSErr PBGetFInfo(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetFInfo((ParmBlkPtr) paramBlock,(Boolean) async); æRT 24 æRI II-115, IV-148, N24-1, N68-1 æC Trap macro _GetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioFRefNum word --> 26 ioFVersNum byte --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 31 ioFlVersNum byte <-- 32 ioFlFndrInfo 16 bytes <-- 48 ioFlNum long word <-- 52 ioFlStBlk word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 76 ioFlMdDat long word PBGetFInfo returns information about the specified file. If ioFDirIndex is positive, the File Manager returns information about the file whose directory index is ioFDirIndex on the volume specified by ioVRefNum. (See the section “Data Organization on Volumes” if you’re interested in using this method.) Note: If a working directory reference number is specified in ioVRefNum, the File Manager returns information about the file whose directory index is ioFDirIndex in the specified directory. If ioFDirIndex is negative or 0, the File Manager returns information about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetFInfoSync æFc Files.h æT Function æTN A00C æD #pragma parameter __D0 PBGetFInfoSync(__A0) pascal OSErr PBGetFInfoSync(ParmBlkPtr paramBlock) = 0xA00C; æDT #pragma parameter __D0 myVariable = PBGetFInfoSync()(__A0); æRT 24 æRI II-115, IV-148, N24-1, N68-1 æC Trap macro _GetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioFRefNum word --> 26 ioFVersNum byte --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 31 ioFlVersNum byte <-- 32 ioFlFndrInfo 16 bytes <-- 48 ioFlNum long word <-- 52 ioFlStBlk word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 76 ioFlMdDat long word PBGetFInfo returns information about the specified file. If ioFDirIndex is positive, the File Manager returns information about the file whose directory index is ioFDirIndex on the volume specified by ioVRefNum. (See the section “Data Organization on Volumes” if you’re interested in using this method.) Note: If a working directory reference number is specified in ioVRefNum, the File Manager returns information about the file whose directory index is ioFDirIndex in the specified directory. If ioFDirIndex is negative or 0, the File Manager returns information about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetFInfoAsync æFc Files.h æT Function æTN A40C æD #pragma parameter __D0 PBGetFInfoAsync(__A0) pascal OSErr PBGetFInfoAsync(ParmBlkPtr paramBlock) = 0xA40C; æDT #pragma parameter __D0 myVariable = PBGetFInfoAsync()(__A0); æRT 24 æRI II-115, IV-148, N24-1, N68-1 æC Trap macro _GetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioFRefNum word --> 26 ioFVersNum byte --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 31 ioFlVersNum byte <-- 32 ioFlFndrInfo 16 bytes <-- 48 ioFlNum long word <-- 52 ioFlStBlk word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 76 ioFlMdDat long word PBGetFInfo returns information about the specified file. If ioFDirIndex is positive, the File Manager returns information about the file whose directory index is ioFDirIndex on the volume specified by ioVRefNum. (See the section “Data Organization on Volumes” if you’re interested in using this method.) Note: If a working directory reference number is specified in ioVRefNum, the File Manager returns information about the file whose directory index is ioFDirIndex in the specified directory. If ioFDirIndex is negative or 0, the File Manager returns information about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBSetFInfo æFc Files.h æT Function æD pascal OSErr PBSetFInfo(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetFInfo((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-116, IV-150 æC Trap macro _SetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte --> 32 ioFlFndrInfo 16 bytes --> 72 ioFlCrDat long word --> 76 ioFlMdDat long word PBSetFInfo sets information (including the date and time of creation and modification, and information needed by the Finder) about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. You should call PBGetFInfo just before PBSetFInfo, so the current information is present in the parameter block. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFInfoSync æFc Files.h æT Function æTN A00D æD #pragma parameter __D0 PBSetFInfoSync(__A0) pascal OSErr PBSetFInfoSync(ParmBlkPtr paramBlock) = 0xA00D; æDT #pragma parameter __D0 myVariable = PBSetFInfoSync()(__A0); æRI II-116, IV-150 æC Trap macro _SetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte --> 32 ioFlFndrInfo 16 bytes --> 72 ioFlCrDat long word --> 76 ioFlMdDat long word PBSetFInfo sets information (including the date and time of creation and modification, and information needed by the Finder) about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. You should call PBGetFInfo just before PBSetFInfo, so the current information is present in the parameter block. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFInfoAsync æFc Files.h æT Function æTN A40D æD #pragma parameter __D0 PBSetFInfoAsync(__A0) pascal OSErr PBSetFInfoAsync(ParmBlkPtr paramBlock) = 0xA40D; æDT #pragma parameter __D0 myVariable = PBSetFInfoAsync()(__A0); æRI II-116, IV-150 æC Trap macro _SetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte --> 32 ioFlFndrInfo 16 bytes --> 72 ioFlCrDat long word --> 76 ioFlMdDat long word PBSetFInfo sets information (including the date and time of creation and modification, and information needed by the Finder) about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. You should call PBGetFInfo just before PBSetFInfo, so the current information is present in the parameter block. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFLock æFc Files.h æT Function æD pascal OSErr PBSetFLock(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetFLock((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-116, IV-151 æC Trap macro _SetFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFLockSync æFc Files.h æT Function æTN A041 æD #pragma parameter __D0 PBSetFLockSync(__A0) pascal OSErr PBSetFLockSync(ParmBlkPtr paramBlock) = 0xA041; æDT #pragma parameter __D0 myVariable = PBSetFLockSync()(__A0); æRI II-116, IV-151 æC Trap macro _SetFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFLockAsync æFc Files.h æT Function æTN A441 æD #pragma parameter __D0 PBSetFLockAsync(__A0) pascal OSErr PBSetFLockAsync(ParmBlkPtr paramBlock) = 0xA441; æDT #pragma parameter __D0 myVariable = PBSetFLockAsync()(__A0); æRI II-116, IV-151 æC Trap macro _SetFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRstFLock æFc Files.h æT Function æD pascal OSErr PBRstFLock(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBRstFLock((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-117, IV-152 æC Trap macro _RstFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRstFLockSync æFc Files.h æT Function æTN A042 æD #pragma parameter __D0 PBRstFLockSync(__A0) pascal OSErr PBRstFLockSync(ParmBlkPtr paramBlock) = 0xA042; æDT #pragma parameter __D0 myVariable = PBRstFLockSync()(__A0); æRI II-117, IV-152 æC Trap macro _RstFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRstFLockAsync æFc Files.h æT Function æTN A442 æD #pragma parameter __D0 PBRstFLockAsync(__A0) pascal OSErr PBRstFLockAsync(ParmBlkPtr paramBlock) = 0xA442; æDT #pragma parameter __D0 myVariable = PBRstFLockAsync()(__A0); æRI II-117, IV-152 æC Trap macro _RstFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFVers æFc Files.h æT Function æD pascal OSErr PBSetFVers(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetFVers((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-117, IV-153 æC Trap macro _SetFilType Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc byte PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers changes the version number of the file having the name pointed to by ioNamePtr and version number ioVersNum, on the volume specified by ioVRefNum, to the version number stored in the high-order byte of ioMisc. Access paths currently in use aren’t affected. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock wrgVolTypErr Attempt to perform hierarchical operation on a flat volume æKY PBSetFVersSync æFc Files.h æT Function æTN A043 æD #pragma parameter __D0 PBSetFVersSync(__A0) pascal OSErr PBSetFVersSync(ParmBlkPtr paramBlock) = 0xA043; æDT #pragma parameter __D0 myVariable = PBSetFVersSync()(__A0); æRI II-117, IV-153 æC Trap macro _SetFilType Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc byte PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers changes the version number of the file having the name pointed to by ioNamePtr and version number ioVersNum, on the volume specified by ioVRefNum, to the version number stored in the high-order byte of ioMisc. Access paths currently in use aren’t affected. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock wrgVolTypErr Attempt to perform hierarchical operation on a flat volume æKY PBSetFVersAsync æFc Files.h æT Function æTN A443 æD #pragma parameter __D0 PBSetFVersAsync(__A0) pascal OSErr PBSetFVersAsync(ParmBlkPtr paramBlock) = 0xA443; æDT #pragma parameter __D0 myVariable = PBSetFVersAsync()(__A0); æRI II-117, IV-153 æC Trap macro _SetFilType Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc byte PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers changes the version number of the file having the name pointed to by ioNamePtr and version number ioVersNum, on the volume specified by ioVRefNum, to the version number stored in the high-order byte of ioMisc. Access paths currently in use aren’t affected. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock wrgVolTypErr Attempt to perform hierarchical operation on a flat volume æKY PBAllocate æFc Files.h æT Function æD pascal OSErr PBAllocate(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBAllocate((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-113, IV-143 æC Trap macro _Allocate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocate adds ioReqCount bytes to the open file whose access path is specified by ioRefNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in ioActCount. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Note: Even if the total number of requested bytes is unavailable, PBAllocate will allocate whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContig instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing wrPermErr Read/write permission doesn’t allow writing æKY PBAllocateSync æFc Files.h æT Function æTN A010 æD #pragma parameter __D0 PBAllocateSync(__A0) pascal OSErr PBAllocateSync(ParmBlkPtr paramBlock) = 0xA010; æDT #pragma parameter __D0 myVariable = PBAllocateSync()(__A0); æRI II-113, IV-143 æC Trap macro _Allocate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocate adds ioReqCount bytes to the open file whose access path is specified by ioRefNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in ioActCount. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Note: Even if the total number of requested bytes is unavailable, PBAllocate will allocate whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContig instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing wrPermErr Read/write permission doesn’t allow writing æKY PBAllocateAsync æFc Files.h æT Function æTN A410 æD #pragma parameter __D0 PBAllocateAsync(__A0) pascal OSErr PBAllocateAsync(ParmBlkPtr paramBlock) = 0xA410; æDT #pragma parameter __D0 myVariable = PBAllocateAsync()(__A0); æRI II-113, IV-143 æC Trap macro _Allocate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocate adds ioReqCount bytes to the open file whose access path is specified by ioRefNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in ioActCount. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Note: Even if the total number of requested bytes is unavailable, PBAllocate will allocate whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContig instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing wrPermErr Read/write permission doesn’t allow writing æKY PBGetEOF æFc Files.h æT Function æD pascal OSErr PBGetEOF(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetEOF((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-112, IV-142 æC Trap macro _GetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 28 ioMisc long word PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose access path is specified by ioRefNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY PBGetEOFSync æFc Files.h æT Function æTN A011 æD #pragma parameter __D0 PBGetEOFSync(__A0) pascal OSErr PBGetEOFSync(ParmBlkPtr paramBlock) = 0xA011; æDT #pragma parameter __D0 myVariable = PBGetEOFSync()(__A0); æRI II-112, IV-142 æC Trap macro _GetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 28 ioMisc long word PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose access path is specified by ioRefNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY PBGetEOFAsync æFc Files.h æT Function æTN A411 æD #pragma parameter __D0 PBGetEOFAsync(__A0) pascal OSErr PBGetEOFAsync(ParmBlkPtr paramBlock) = 0xA411; æDT #pragma parameter __D0 myVariable = PBGetEOFAsync()(__A0); æRI II-112, IV-142 æC Trap macro _GetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 28 ioMisc long word PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose access path is specified by ioRefNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY PBSetEOF æFc Files.h æT Function æD pascal OSErr PBSetEOF(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetEOF((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-112, IV-142 æC Trap macro _SetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 28 ioMisc long word PBSetEOF sets the logical end-of-file of the open file, whose access path is specified by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file beyond the physical end-of-file, another allocation block is added to the file; if there isn’t enough space on the volume, no change is made, and PBSetEOF returns dskFulErr as its function result. If ioMisc is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBSetEOFSync æFc Files.h æT Function æTN A012 æD #pragma parameter __D0 PBSetEOFSync(__A0) pascal OSErr PBSetEOFSync(ParmBlkPtr paramBlock) = 0xA012; æDT #pragma parameter __D0 myVariable = PBSetEOFSync()(__A0); æRI II-112, IV-142 æC Trap macro _SetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 28 ioMisc long word PBSetEOF sets the logical end-of-file of the open file, whose access path is specified by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file beyond the physical end-of-file, another allocation block is added to the file; if there isn’t enough space on the volume, no change is made, and PBSetEOF returns dskFulErr as its function result. If ioMisc is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBSetEOFAsync æFc Files.h æT Function æTN A412 æD #pragma parameter __D0 PBSetEOFAsync(__A0) pascal OSErr PBSetEOFAsync(ParmBlkPtr paramBlock) = 0xA412; æDT #pragma parameter __D0 myVariable = PBSetEOFAsync()(__A0); æRI II-112, IV-142 æC Trap macro _SetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 28 ioMisc long word PBSetEOF sets the logical end-of-file of the open file, whose access path is specified by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file beyond the physical end-of-file, another allocation block is added to the file; if there isn’t enough space on the volume, no change is made, and PBSetEOF returns dskFulErr as its function result. If ioMisc is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBGetFPos æFc Files.h æT Function æD pascal OSErr PBGetFPos(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetFPos((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-111, IV-141 æC Trap macro _GetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 36 ioReqCount long word <-- 40 ioActCount long word <-- 44 ioPosMode word <-- 46 ioPosOffset long word PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path is specified by ioRefNum. It sets ioReqCount, ioActCount, and ioPosMode to 0. Result codes noErr No error extFSErr External file system fnOpnErr File not open gfpErr Error during GetFPos ioErr I/O error rfNumErr Bad reference number æKY PBGetFPosSync æFc Files.h æT Function æTN A018 æD #pragma parameter __D0 PBGetFPosSync(__A0) pascal OSErr PBGetFPosSync(ParmBlkPtr paramBlock) = 0xA018; æDT #pragma parameter __D0 myVariable = PBGetFPosSync()(__A0); æRI II-111, IV-141 æC Trap macro _GetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 36 ioReqCount long word <-- 40 ioActCount long word <-- 44 ioPosMode word <-- 46 ioPosOffset long word PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path is specified by ioRefNum. It sets ioReqCount, ioActCount, and ioPosMode to 0. Result codes noErr No error extFSErr External file system fnOpnErr File not open gfpErr Error during GetFPos ioErr I/O error rfNumErr Bad reference number æKY PBGetFPosAsync æFc Files.h æT Function æTN A418 æD #pragma parameter __D0 PBGetFPosAsync(__A0) pascal OSErr PBGetFPosAsync(ParmBlkPtr paramBlock) = 0xA418; æDT #pragma parameter __D0 myVariable = PBGetFPosAsync()(__A0); æRI II-111, IV-141 æC Trap macro _GetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 36 ioReqCount long word <-- 40 ioActCount long word <-- 44 ioPosMode word <-- 46 ioPosOffset long word PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path is specified by ioRefNum. It sets ioReqCount, ioActCount, and ioPosMode to 0. Result codes noErr No error extFSErr External file system fnOpnErr File not open gfpErr Error during GetFPos ioErr I/O error rfNumErr Bad reference number æKY PBSetFPos æFc Files.h æT Function æD pascal OSErr PBSetFPos(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetFPos((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-111, IV-141 æC Trap macro _SetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBSetFPos sets the mark of the open file whose access path is specified by ioRefNum to the position specified by ioPosMode and ioPosOffset. The position at which the mark is actually set is returned in ioPosOffset. If you try to set the mark past the logical end-of-file, PBSetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY PBSetFPosSync æFc Files.h æT Function æTN A044 æD #pragma parameter __D0 PBSetFPosSync(__A0) pascal OSErr PBSetFPosSync(ParmBlkPtr paramBlock) = 0xA044; æDT #pragma parameter __D0 myVariable = PBSetFPosSync()(__A0); æRI II-111, IV-141 æC Trap macro _SetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBSetFPos sets the mark of the open file whose access path is specified by ioRefNum to the position specified by ioPosMode and ioPosOffset. The position at which the mark is actually set is returned in ioPosOffset. If you try to set the mark past the logical end-of-file, PBSetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY PBSetFPosAsync æFc Files.h æT Function æTN A444 æD #pragma parameter __D0 PBSetFPosAsync(__A0) pascal OSErr PBSetFPosAsync(ParmBlkPtr paramBlock) = 0xA444; æDT #pragma parameter __D0 myVariable = PBSetFPosAsync()(__A0); æRI II-111, IV-141 æC Trap macro _SetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBSetFPos sets the mark of the open file whose access path is specified by ioRefNum to the position specified by ioPosMode and ioPosOffset. The position at which the mark is actually set is returned in ioPosOffset. If you try to set the mark past the logical end-of-file, PBSetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY PBFlushFile æFc Files.h æT Function æD pascal OSErr PBFlushFile(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBFlushFile((ParmBlkPtr) paramBlock,(Boolean) async); æRI II-114, IV-144 æC Trap macro _FlushFile Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBFlushFile writes the contents of the access path buffer indicated by ioRefNum to the volume, and updates the file’s entry in the file directory (or in the file catalog, in the case of hierarchical volumes). Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBFlushFileSync æFc Files.h æT Function æTN A045 æD #pragma parameter __D0 PBFlushFileSync(__A0) pascal OSErr PBFlushFileSync(ParmBlkPtr paramBlock) = 0xA045; æDT #pragma parameter __D0 myVariable = PBFlushFileSync()(__A0); æRI II-114, IV-144 æC Trap macro _FlushFile Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBFlushFile writes the contents of the access path buffer indicated by ioRefNum to the volume, and updates the file’s entry in the file directory (or in the file catalog, in the case of hierarchical volumes). Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBFlushFileAsync æFc Files.h æT Function æTN A445 æD #pragma parameter __D0 PBFlushFileAsync(__A0) pascal OSErr PBFlushFileAsync(ParmBlkPtr paramBlock) = 0xA445; æDT #pragma parameter __D0 myVariable = PBFlushFileAsync()(__A0); æRI II-114, IV-144 æC Trap macro _FlushFile Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBFlushFile writes the contents of the access path buffer indicated by ioRefNum to the volume, and updates the file’s entry in the file directory (or in the file catalog, in the case of hierarchical volumes). Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBMountVol æFc Files.h æT Function æTN A00F æD #pragma parameter __D0 PBMountVol(__A0) pascal OSErr PBMountVol(ParmBlkPtr paramBlock) = 0xA00F; æDT #pragma parameter __D0 myVariable = PBMountVol()(__A0); æMM æRT 134 æRI II-103, IV-128 æC »Accessing Volumes To get the volume reference number of a volume, given the path reference number of a file on that volume, both Pascal and assembly-language programmers can call the high-level File Manager function GetVRefNum. Assembly-language programmers may prefer calling the function GetFCBInfo (described below in the section “Data Structures in Memory”). FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; Trap macro _MountVol Parameter block <-- 16 ioResult word <-> 22 ioVRefNum word PBMountVol mounts the volume in the drive specified by ioVRefNum, and returns a volume reference number in ioVRefNum. If there are no volumes already mounted, this volume becomes the default volume. PBMountVol is always executed synchronously. Note: When mounting hierarchical volumes, PBMountVol opens two files needed for maintaining file directory and file mapping information. PBMountVol can fail if there are no access paths available for these two files; it will return tmfoErr as its function result. Result codes noErr No error badMDBErr Bad master directory block extFSErr External file system ioErr I/O error memFullErr Not enough room in heap zone noMacDskErr Not a Macintosh disk nsDrvErr No such drive paramErr Bad drive number tmfoErr Too many files open volOnLinErr Volume already on-line æKY PBUnmountVol æFc Files.h æT Function æTN A00E æD #pragma parameter __D0 PBUnmountVol(__A0) pascal OSErr PBUnmountVol(ParmBlkPtr paramBlock) = 0xA00E; æDT #pragma parameter __D0 myVariable = PBUnmountVol()(__A0); æRI II-106, IV-134 æC Trap macro _UnmountVol Parameter block <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBUnmountVol unmounts the volume specified by ioNamePtr or ioVRefNum, by calling PBFlushVol to flush the volume, closing all open files on the volume, and releasing the memory used for the volume. PBUnmountVol is always executed synchronously. Warning: Don’t unmount the startup volume. Note: Unmounting a volume does not close working directories; to release the memory allocated to a working directory, call PBCloseWD. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBEject æFc Files.h æT Function æTN A017 æD #pragma parameter __D0 PBEject(__A0) pascal OSErr PBEject(ParmBlkPtr paramBlock) = 0xA017; æDT #pragma parameter __D0 myVariable = PBEject()(__A0); æMM æRI II-107, IV-135 æC Trap macro _Eject Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBEject flushes the volume specified by ioNamePtr or ioVRefNum, places it off-line, and then ejects the volume. Assembly-language note: You may invoke the macro _Eject asynchronously; the first part of the call is executed synchronously, and the actual ejection is executed asynchronously. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBOffLine æFc Files.h æT Function æTN A035 æD #pragma parameter __D0 PBOffLine(__A0) pascal OSErr PBOffLine(ParmBlkPtr paramBlock) = 0xA035; æDT #pragma parameter __D0 myVariable = PBOffLine()(__A0); æMM æRI II-106, IV-134 æC Trap macro _OffLine Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBOffLine places off-line the volume specified by ioNamePtr or ioVRefNum, by calling PBFlushVol to flush the volume and releasing all the memory used for the volume except for the volume control block. PBOffLine is always executed synchronously. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBCatSearch æFc Files.h æT Function æD pascal OSErr PBCatSearch(CSParamPtr paramBlock,Boolean async); æDT OSErr myVariable = PBCatSearch((CSParamPtr) paramBlock,(Boolean) async); æMM æRI PBOffLine function II-106, IV-134 æC æKY PBCatSearchSync æFc Files.h æT Function æTN 7018,A260 æD #pragma parameter __D0 PBCatSearchSync(__A0) pascal OSErr PBCatSearchSync(CSParamPtr paramBlock) = {0x7018,0xA260}; æDT #pragma parameter __D0 myVariable = PBCatSearchSync()(__A0); æMM æRI PBOffLine function II-106, IV-134 æC æKY PBCatSearchAsync æFc Files.h æT Function æTN 7018,A660 æD #pragma parameter __D0 PBCatSearchAsync(__A0) pascal OSErr PBCatSearchAsync(CSParamPtr paramBlock) = {0x7018,0xA660}; æDT #pragma parameter __D0 myVariable = PBCatSearchAsync()(__A0); æMM æRI PBOffLine function II-106, IV-134 æC æKY AddDrive æFc Files.h æT Function æD pascal void AddDrive(short drvrRefNum,short drvNum,DrvQElPtr qEl); æDT AddDrive((short) drvrRefNum,(short) drvNum,(DrvQElPtr) qEl); æRT 36, 108 æRI N36, N108-1 æC æKY FSOpen æFc Files.h æT Function æD pascal OSErr FSOpen(ConstStr255Param fileName,short vRefNum,short *refNum); æDT OSErr myVariable = FSOpen((ConstStr255Param) fileName,(short) vRefNum,(short *) refNum); æRT 102 æRI II-91, IV-109, P-131, 171 æC [Not in ROM] FSOpen creates an access path to the file having the name fileName on the volume specified by vRefNum. A path reference number is returned in refNum. The access path’s read/write permission is set to whatever the file’s open permission allows. Note: There’s no guarantee that any bytes have been written until FlushVol is called. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing tmfoErr Too many files open æKY OpenDF æFc Files.h æT Function æD pascal OSErr OpenDF(ConstStr255Param fileName,short vRefNum,short *refNum); æDT OSErr myVariable = OpenDF((ConstStr255Param) fileName,(short) vRefNum,(short *) refNum); æRT 102 æRI II-91, IV-109, P-131, 171 æC [Not in ROM] FSOpen creates an access path to the file having the name fileName on the volume specified by vRefNum. A path reference number is returned in refNum. The access path’s read/write permission is set to whatever the file’s open permission allows. Note: There’s no guarantee that any bytes have been written until FlushVol is called. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing tmfoErr Too many files open æKY fsopen æFc Files.h æT Function æD OSErr fsopen(char *fileName,short vRefNum,short *refNum); æDT OSErr myVariable = fsopen((char *) fileName,(short) vRefNum,(short *) refNum); æC æKY FSClose æFc Files.h æT Function æD pascal OSErr FSClose(short refNum); æDT OSErr myVariable = FSClose((short) refNum); æRT 102 æRI II-94, IV-112, P-132, 133, 171 æC [Not in ROM] FSClose removes the access path specified by refNum, writes the contents of the volume buffer to the volume, and updates the file’s entry in the file directory. Note: There’s no guarantee that any bytes have been written until FlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY FSRead æFc Files.h æT Function æD pascal OSErr FSRead(short refNum,long *count,void *buffPtr); æDT OSErr myVariable = FSRead((short) refNum,(long *) count,(void *) buffPtr); æRI IV-109, P-131, 171 æC [Not in ROM] FSRead attempts to read the number of bytes specified by the count parameter from the open file whose access path is specified by refNum, and transfer them to the data buffer pointed to by buffPtr. The read operation begins at the current mark, so you might want to precede this with a call to SetFPos. If you try to read past the logical end-of-file, FSRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the number of bytes actually read is returned in the count parameter. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative count rfNumErr Bad reference number æKY FSWrite æFc Files.h æT Function æD pascal OSErr FSWrite(short refNum,long *count,const void *buffPtr); æDT OSErr myVariable = FSWrite((short) refNum,(long *) count,(const void *) buffPtr); æRI IV-110, P-132, 171 æC [Not in ROM] FSWrite takes the number of bytes specified by the count parameter from the buffer pointed to by buffPtr and attempts to write them to the open file whose access path is specified by refNum. The write operation begins at the current mark, so you might want to precede this with a call to SetFPos. After the write is completed, the number of bytes actually written is returned in the count parameter. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative count rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY GetVInfo æFc Files.h æT Function æD pascal OSErr GetVInfo(short drvNum,StringPtr volName,short *vRefNum,long *freeBytes); æDT OSErr myVariable = GetVInfo((short) drvNum,(StringPtr) volName,(short *) vRefNum,(long *) freeBytes); æRT 157 æRI II-89, IV-107, N157, low-level II-104, IV-129 æC »Accessing Volumes •••Refer to Technical Note #24:••• FUNCTION GetVInfo (drvNum: INTEGER; volName: StringPtr; VAR vRefNum: INTEGER; VAR freeBytes: LONGINT) : OSErr; [Not in ROM] •••Refer to Technical Note #157:••• GetVInfo returns the name, reference number, and available space (in bytes), in volName, vRefNum, and freeBytes, for the volume in the drive specified by drvNum. Result codes noErr No error nsvErr No default volume paramErr Bad drive number æKY getvinfo æFc Files.h æT Function æD OSErr getvinfo(short drvNum,char *volName,short *vRefNum,long *freeBytes); æDT OSErr myVariable = getvinfo((short) drvNum,(char *) volName,(short *) vRefNum,(long *) freeBytes); æC æKY GetFInfo æFc Files.h æT Function æD pascal OSErr GetFInfo(ConstStr255Param fileName,short vRefNum,FInfo *fndrInfo); æDT OSErr myVariable = GetFInfo((ConstStr255Param) fileName,(short) vRefNum,(FInfo *) fndrInfo); æRI II-95, IV-113 æC [Not in ROM] For the file having the name fileName on the specified volume, GetFInfo returns information used by the Finder in fndrInfo (see the section “Information Used by the Finder”). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY getfinfo æFc Files.h æT Function æD OSErr getfinfo(char *fileName,short vRefNum,FInfo *fndrInfo); æDT OSErr myVariable = getfinfo((char *) fileName,(short) vRefNum,(FInfo *) fndrInfo); æC æKY GetVol æFc Files.h æT Function æD pascal OSErr GetVol(StringPtr volName,short *vRefNum); æDT OSErr myVariable = GetVol((StringPtr) volName,(short *) vRefNum); æRT 77,140 æRI N77-2, N140 high-level II-89, IV-107 low-level II-104, IV-131 æC [Not in ROM] GetVol returns the name of the default volume in volName and its volume reference number in vRefNum. Result codes noErr No error nsvErr No such volume æKY getvol æFc Files.h æT Function æD OSErr getvol(char *volName,short *vRefNum); æDT OSErr myVariable = getvol((char *) volName,(short *) vRefNum); æC æKY SetVol æFc Files.h æT Function æD pascal OSErr SetVol(StringPtr volName,short vRefNum); æDT OSErr myVariable = SetVol((StringPtr) volName,(short) vRefNum); æRI II-89, IV-107 low-level II-105, IV-132 æC [Not in ROM] SetVol sets the default volume to the mounted volume specified by volName or vRefNum. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY setvol æFc Files.h æT Function æD OSErr setvol(char *volName,short vRefNum); æDT OSErr myVariable = setvol((char *) volName,(short) vRefNum); æC æKY UnmountVol æFc Files.h æT Function æD pascal OSErr UnmountVol(StringPtr volName,short vRefNum); æDT OSErr myVariable = UnmountVol((StringPtr) volName,(short) vRefNum); æRT 180 æRI II-90, IV-108 low-level II-106, IV-134 æC [Not in ROM] UnmountVol unmounts the volume specified by volName or vRefNum, by calling FlushVol to flush the volume buffer, closing all open files on the volume, and releasing the memory used for the volume. Warning: Don’t unmount the startup volume. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY unmountvol æFc Files.h æT Function æD OSErr unmountvol(char *volName,short vRefNum); æDT OSErr myVariable = unmountvol((char *) volName,(short) vRefNum); æC æKY Eject æFc Files.h æT Function æD pascal OSErr Eject(StringPtr volName,short vRefNum); æDT OSErr myVariable = Eject((StringPtr) volName,(short) vRefNum); æMM æRI II-90, IV-108 low-level II-107, IV-135 æC [Not in ROM] Eject flushes the volume specified by volName or vRefNum, places it off-line, and then ejects the volume. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY eject æFc Files.h æT Function æD OSErr eject(char *volName,short vRefNum); æDT OSErr myVariable = eject((char *) volName,(short) vRefNum); æC æKY FlushVol æFc Files.h æT Function æD pascal OSErr FlushVol(StringPtr volName,short vRefNum); æDT OSErr myVariable = FlushVol((StringPtr) volName,(short) vRefNum); æMM æRI P-132, 133 high-level II-89, IV-108 low-level II-105, IV-133 æC [Not in ROM] On the volume specified by volName or vRefNum, FlushVol writes the contents of the associated volume buffer and descriptive information about the volume (if they’ve changed since the last time FlushVol was called). Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY flushvol æFc Files.h æT Function æD OSErr flushvol(char *volName,short vRefNum); æDT OSErr myVariable = flushvol((char *) volName,(short) vRefNum); æC æKY Create æFc Files.h æT Function æD pascal OSErr Create(ConstStr255Param fileName,short vRefNum,OSType creator, OSType fileType); æDT OSErr myVariable = Create((ConstStr255Param) fileName,(short) vRefNum,(OSType) creator,() OSType fileType); æRI II-90, IV-112 low-level II-107, IV-145 æC [Not in ROM] Create creates a new file (both forks) with the specified name, file type, and creator on the specified volume. (File type and creator are discussed in the Finder Interface chapter.) The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY create æFc Files.h æT Function æD OSErr create(char *fileName,short vRefNum,OSType creator,OSType fileType); æDT OSErr myVariable = create((char *) fileName,(short) vRefNum,(OSType) creator,(OSType) fileType); æRI II-90, IV-112 low-level II-107, IV-145 æC Create creates a new file (both forks) with the specified name, file type, and creator on the specified volume. (File type and creator are discussed in the Finder Interface chapter.) The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY FSDelete æFc Files.h æT Function æD pascal OSErr FSDelete(ConstStr255Param fileName,short vRefNum); æDT OSErr myVariable = FSDelete((ConstStr255Param) fileName,(short) vRefNum); æRI II-97, IV-113 æC [Not in ROM] FSDelete removes the closed file having the name fileName from the specified volume. Note: This function will delete both forks of a file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY fsdelete æFc Files.h æT Function æD OSErr fsdelete(char *fileName,short vRefNum); æDT OSErr myVariable = fsdelete((char *) fileName,(short) vRefNum); æC æKY OpenRF æFc Files.h æT Function æD pascal OSErr OpenRF(ConstStr255Param fileName,short vRefNum,short *refNum); æDT OSErr myVariable = OpenRF((ConstStr255Param) fileName,(short) vRefNum,(short *) refNum); æRT 74 æRI II-91, IV-109 low-level II-109, IV-137 æC [Not in ROM] OpenRF is similar to FSOpen; the only difference is that OpenRF opens the resource fork of the specified file rather than the data fork. A path reference number is returned in refNum. The access path’s read/write permission is set to whatever the file’s open permission allows. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. OpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing tmfoErr Too many files open æKY openrf æFc Files.h æT Function æD OSErr openrf(char *fileName,short vRefNum,short *refNum); æDT OSErr myVariable = openrf((char *) fileName,(short) vRefNum,(short *) refNum); æC æKY Rename æFc Files.h æT Function æD pascal OSErr Rename(ConstStr255Param oldName,short vRefNum,ConstStr255Param newName); æDT OSErr myVariable = Rename((ConstStr255Param) oldName,(short) vRefNum,(ConstStr255Param) newName); æRI II-96, IV-114 low-level II-118, IV-153 æC [Not in ROM] Given a file name in oldName, Rename changes the name of the file to newName. Access paths currently in use aren’t affected. Given a volume name in oldName or a volume reference number in vRefNum, Rename changes the name of the specified volume to newName. Warning: If you’re renaming a volume, be sure that both names end with a colon. Result codes noErr No error bdNamErr Bad file name dirFulErr Directory full dupFNErr Duplicate file name extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY fsrename æFc Files.h æT Function æD OSErr fsrename(char *oldName,short vRefNum,char *newName); æDT OSErr myVariable = fsrename((char *) oldName,(short) vRefNum,(char *) newName); æRI II-96, IV-114 low-level II-118, IV-153 æC fsrename is actually the "c" version of the Macintosh ROM call, Rename, which uses c strings. It was not named "rename" to avoid conflict with the ANSI call by that name. æKY SetFInfo æFc Files.h æT Function æD pascal OSErr SetFInfo(ConstStr255Param fileName,short vRefNum,const FInfo *fndrInfo); æDT OSErr myVariable = SetFInfo((ConstStr255Param) fileName,(short) vRefNum,(const FInfo *) fndrInfo); æRI II-95, IV-114 æC [Not in ROM] For the file having the name fileName on the specified volume, SetFInfo sets information used by the Finder to fndrInfo (see the section “Information Used by the Finder”). Result codes noErr No error extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY setfinfo æFc Files.h æT Function æD OSErr setfinfo(char *fileName,short vRefNum,FInfo *fndrInfo); æDT OSErr myVariable = setfinfo((char *) fileName,(short) vRefNum,(FInfo *) fndrInfo); æC æKY SetFLock æFc Files.h æT Function æD pascal OSErr SetFLock(ConstStr255Param fileName,short vRefNum); æDT OSErr myVariable = SetFLock((ConstStr255Param) fileName,(short) vRefNum); æRI II-95, IV-114 æC [Not in ROM] SetFLock locks the file having the name fileName on the specified volume. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY setflock æFc Files.h æT Function æD OSErr setflock(char *fileName,short vRefNum); æDT OSErr myVariable = setflock((char *) fileName,(short) vRefNum); æC æKY RstFLock æFc Files.h æT Function æD pascal OSErr RstFLock(ConstStr255Param fileName,short vRefNum); æDT OSErr myVariable = RstFLock((ConstStr255Param) fileName,(short) vRefNum); æRI II-96, IV-114 æC [Not in ROM] RstFLock unlocks the file having the name fileName on the specified volume. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY rstflock æFc Files.h æT Function æD OSErr rstflock(char *fileName,short vRefNum); æDT OSErr myVariable = rstflock((char *) fileName,(short) vRefNum); æC æKY Allocate æFc Files.h æT Function æD pascal OSErr Allocate(short refNum,long *count); æDT OSErr myVariable = Allocate((short) refNum,(long *) count); æRI IV-143 æC [Not in ROM] Allocate adds the number of bytes specified by the count parameter to the open file whose access path is specified by refNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in the count parameter. If there isn’t enough empty space on the volume to satisfy the allocation request, Allocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY GetEOF æFc Files.h æT Function æD pascal OSErr GetEOF(short refNum,long *logEOF); æDT OSErr myVariable = GetEOF((short) refNum,(long *) logEOF); æRI P-132, 172 high-level II-93, IV-111 low-level II-112, IV-142 æC [Not in ROM] GetEOF returns, in logEOF, the logical end-of-file of the open file whose access path is specified by refNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY SetEOF æFc Files.h æT Function æD pascal OSErr SetEOF(short refNum,long logEOF); æDT OSErr myVariable = SetEOF((short) refNum,(long) logEOF); æRI P-132, 180 high-level II-93, IV-111 low-level II-112, IV-142 æC [Not in ROM] SetEOF sets the logical end-of-file of the open file whose access path is specified by refNum to the position specified by logEOF. If you attempt to set the logical end-of-file beyond the physical end-of-file, the physical end-of-file is set to one byte beyond the end of the next free allocation block; if there isn’t enough space on the volume, no change is made, and SetEOF returns dskFulErr as its function result. If logEOF is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY GetFPos æFc Files.h æT Function æD pascal OSErr GetFPos(short refNum,long *filePos); æDT OSErr myVariable = GetFPos((short) refNum,(long *) filePos); æRI II-92, IV-110 low-level II-111, IV-141 æC [Not in ROM] GetFPos returns, in filePos, the mark of the open file whose access path is specified by refNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY SetFPos æFc Files.h æT Function æD pascal OSErr SetFPos(short refNum,short posMode,long posOff); æDT OSErr myVariable = SetFPos((short) refNum,(short) posMode,(long) posOff); æRI P-131, 132, 180 high-level II-93, IV-110 low-level II-111, IV-141 æC [Not in ROM] SetFPos sets the mark of the open file whose access path is specified by refNum to the position specified by posMode and posOff (except when posMode is equal to fsAtMark, in which case posOff is ignored). PosMode indicates how to position the mark; it must contain one of the following values: CONST fsAtMark = 0; {at current mark} fsFromStart = 1; {set mark relative to beginning of file} fsFromLEOF = 2; {set mark relative to logical end-of-file} fsFromMark = 3; {set mark relative to current mark} If you specify fsAtMark, posOffset is ignored and the mark is left wherever it’s currently positioned. If you choose to set the mark (relative to either the beginning of the file, the logical end-of-file, or the current mark), posOffset specifies the byte offset from the chosen point (either positive or negative) where the mark should be set. If you try to set the mark past the logical end-of-file, SetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY GetVRefNum æFc Files.h æT Function æD pascal OSErr GetVRefNum(short fileRefNum,short *vRefNum); æDT OSErr myVariable = GetVRefNum((short) fileRefNum,(short *) vRefNum); æRI II-89, IV-107 æC [Not in ROM] Given a path reference number in pathRefNum, GetVRefNum returns the volume reference number in vRefNum. Result codes noErr No error rfNumErr Bad reference number æKY PBOpenWD æFc Files.h æT Function æD pascal OSErr PBOpenWD(WDPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBOpenWD((WDPBPtr) paramBlock,(Boolean) async); æRT 77, 190 æRI IV-158, N77-1 æC Trap macro _OpenWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioWDProcID long word --> 48 ioWDDirID long word PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID and makes it a working directory. (You can also specify the directory using a combination of partial pathname and directory ID.) It returns a working directory reference number in ioVRefNum that can be used in subsequent calls. If a given directory has already been made a working directory using the same ioWDProcID, no new working directory will be opened; instead, the existing working directory reference number will be returned. If a given directory was already made a working directory using a different ioWDProcID, a new working directory reference number is returned. Result codes noErr No error tmwdoErr Too many working directories open æKY PBOpenWDSync æFc Files.h æT Function æTN 7001,A260 æD #pragma parameter __D0 PBOpenWDSync(__A0) pascal OSErr PBOpenWDSync(WDPBPtr paramBlock) = {0x7001,0xA260}; æDT #pragma parameter __D0 myVariable = PBOpenWDSync()(__A0); æRT 77, 190 æRI IV-158, N77-1 æC Trap macro _OpenWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioWDProcID long word --> 48 ioWDDirID long word PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID and makes it a working directory. (You can also specify the directory using a combination of partial pathname and directory ID.) It returns a working directory reference number in ioVRefNum that can be used in subsequent calls. If a given directory has already been made a working directory using the same ioWDProcID, no new working directory will be opened; instead, the existing working directory reference number will be returned. If a given directory was already made a working directory using a different ioWDProcID, a new working directory reference number is returned. Result codes noErr No error tmwdoErr Too many working directories open æKY PBOpenWDAsync æFc Files.h æT Function æTN 7001,A660 æD #pragma parameter __D0 PBOpenWDAsync(__A0) pascal OSErr PBOpenWDAsync(WDPBPtr paramBlock) = {0x7001,0xA660}; æDT #pragma parameter __D0 myVariable = PBOpenWDAsync()(__A0); æRT 77, 190 æRI IV-158, N77-1 æC Trap macro _OpenWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioWDProcID long word --> 48 ioWDDirID long word PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID and makes it a working directory. (You can also specify the directory using a combination of partial pathname and directory ID.) It returns a working directory reference number in ioVRefNum that can be used in subsequent calls. If a given directory has already been made a working directory using the same ioWDProcID, no new working directory will be opened; instead, the existing working directory reference number will be returned. If a given directory was already made a working directory using a different ioWDProcID, a new working directory reference number is returned. Result codes noErr No error tmwdoErr Too many working directories open æKY PBCloseWD æFc Files.h æT Function æD pascal OSErr PBCloseWD(WDPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBCloseWD((WDPBPtr) paramBlock,(Boolean) async); æRI IV-158 æC Trap macro _CloseWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word PBCloseWD releases the working directory whose working directory reference number is specified in ioVRefNum. Note: If a volume reference number is specified in ioVRefNum, PBCloseWD does nothing. Result codes noErr No error nsvErr No such volume æKY PBCloseWDSync æFc Files.h æT Function æTN 7002,A260 æD #pragma parameter __D0 PBCloseWDSync(__A0) pascal OSErr PBCloseWDSync(WDPBPtr paramBlock) = {0x7002,0xA260}; æDT #pragma parameter __D0 myVariable = PBCloseWDSync()(__A0); æRI IV-158 æC Trap macro _CloseWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word PBCloseWD releases the working directory whose working directory reference number is specified in ioVRefNum. Note: If a volume reference number is specified in ioVRefNum, PBCloseWD does nothing. Result codes noErr No error nsvErr No such volume æKY PBCloseWDAsync æFc Files.h æT Function æTN 7002,A660 æD #pragma parameter __D0 PBCloseWDAsync(__A0) pascal OSErr PBCloseWDAsync(WDPBPtr paramBlock) = {0x7002,0xA660}; æDT #pragma parameter __D0 myVariable = PBCloseWDAsync()(__A0); æRI IV-158 æC Trap macro _CloseWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word PBCloseWD releases the working directory whose working directory reference number is specified in ioVRefNum. Note: If a volume reference number is specified in ioVRefNum, PBCloseWD does nothing. Result codes noErr No error nsvErr No such volume æKY PBHSetVol æFc Files.h æT Function æD pascal OSErr PBHSetVol(WDPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBHSetVol((WDPBPtr) paramBlock,(Boolean) async); æRT 140 æRI IV-133, N140 æC •••Refer to Technical Note #140:••• Trap macro _HSetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioWDDirID long word PBHSetVol sets both the default volume and the default directory. The default directory to be used can be specified by either a volume reference number or a working directory reference number in ioVRefNum, a directory ID in ioWDDirID, or a pointer to a pathname (possibly NIL) in ioNamePtr. Note: Both the default volume and the default directory are used in calls made with no volume name and a volume reference number of zero. Result codes noErr No error nsvErr No default volume æKY PBHSetVolSync æFc Files.h æT Function æTN A215 æD #pragma parameter __D0 PBHSetVolSync(__A0) pascal OSErr PBHSetVolSync(WDPBPtr paramBlock) = 0xA215; æDT #pragma parameter __D0 myVariable = PBHSetVolSync()(__A0); æRT 140 æRI IV-133, N140 æC •••Refer to Technical Note #140:••• Trap macro _HSetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioWDDirID long word PBHSetVol sets both the default volume and the default directory. The default directory to be used can be specified by either a volume reference number or a working directory reference number in ioVRefNum, a directory ID in ioWDDirID, or a pointer to a pathname (possibly NIL) in ioNamePtr. Note: Both the default volume and the default directory are used in calls made with no volume name and a volume reference number of zero. Result codes noErr No error nsvErr No default volume æKY PBHSetVolAsync æFc Files.h æT Function æTN A615 æD #pragma parameter __D0 PBHSetVolAsync(__A0) pascal OSErr PBHSetVolAsync(WDPBPtr paramBlock) = 0xA615; æDT #pragma parameter __D0 myVariable = PBHSetVolAsync()(__A0); æRT 140 æRI IV-133, N140 æC •••Refer to Technical Note #140:••• Trap macro _HSetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioWDDirID long word PBHSetVol sets both the default volume and the default directory. The default directory to be used can be specified by either a volume reference number or a working directory reference number in ioVRefNum, a directory ID in ioWDDirID, or a pointer to a pathname (possibly NIL) in ioNamePtr. Note: Both the default volume and the default directory are used in calls made with no volume name and a volume reference number of zero. Result codes noErr No error nsvErr No default volume æKY PBHGetVol æFc Files.h æT Function æD pascal OSErr PBHGetVol(WDPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBHGetVol((WDPBPtr) paramBlock,(Boolean) async); æRI IV-132 æC Trap macro _HGetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word <-- 28 ioWDProcID long word <-- 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBHGetVol returns the default volume and directory last set by either a PBSetVol or a PBHSetVol call. The reference number of the default volume is returned in ioVRefNum. Warning: IOVRefNum will return a working directory reference number (instead of the volume reference number) if, in the last call to PBSetVol or PBHSetVol, a working directory reference number was passed in this field. The volume reference number of the volume on which the default directory exists is returned in ioWDVRefNum. The directory ID of the default directory is returned in ioWDDirID. Result codes noErr No error nsvErr No default volume æKY PBHGetVolSync æFc Files.h æT Function æTN A214 æD #pragma parameter __D0 PBHGetVolSync(__A0) pascal OSErr PBHGetVolSync(WDPBPtr paramBlock) = 0xA214; æDT #pragma parameter __D0 myVariable = PBHGetVolSync()(__A0); æRI IV-132 æC Trap macro _HGetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word <-- 28 ioWDProcID long word <-- 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBHGetVol returns the default volume and directory last set by either a PBSetVol or a PBHSetVol call. The reference number of the default volume is returned in ioVRefNum. Warning: IOVRefNum will return a working directory reference number (instead of the volume reference number) if, in the last call to PBSetVol or PBHSetVol, a working directory reference number was passed in this field. The volume reference number of the volume on which the default directory exists is returned in ioWDVRefNum. The directory ID of the default directory is returned in ioWDDirID. Result codes noErr No error nsvErr No default volume æKY PBHGetVolAsync æFc Files.h æT Function æTN A614 æD #pragma parameter __D0 PBHGetVolAsync(__A0) pascal OSErr PBHGetVolAsync(WDPBPtr paramBlock) = 0xA614; æDT #pragma parameter __D0 myVariable = PBHGetVolAsync()(__A0); æRI IV-132 æC Trap macro _HGetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word <-- 28 ioWDProcID long word <-- 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBHGetVol returns the default volume and directory last set by either a PBSetVol or a PBHSetVol call. The reference number of the default volume is returned in ioVRefNum. Warning: IOVRefNum will return a working directory reference number (instead of the volume reference number) if, in the last call to PBSetVol or PBHSetVol, a working directory reference number was passed in this field. The volume reference number of the volume on which the default directory exists is returned in ioWDVRefNum. The directory ID of the default directory is returned in ioWDDirID. Result codes noErr No error nsvErr No default volume æKY PBCatMove æFc Files.h æT Function æD pascal OSErr PBCatMove(CMovePBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBCatMove((CMovePBPtr) paramBlock,(Boolean) async); æRI IV-157 æC •••Refer to Technical Note #226:••• Trap macro _CatMove Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 28 ioNewName pointer --> 36 ioNewDirID long word --> 48 ioDirID long word PBCatMove moves files or directories from one directory to another. The name of the file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains either the volume reference number or working directory reference number. A directory ID can be specified in ioDirID. The name and directory ID of the directory to which the file or directory is to be moved are specified by ioNewName and ioNewDirID. PBCatMove is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. PBCatMove cannot move a file or directory to another volume (that is, ioVRefNum is used in specifying both the source and the destination). It also cannot be used to rename files or directories; for that, use PBHRename. Result codes noErr No error badMovErr Attempt to move into offspring bdNamErr Bad file name or attempt to move into a file dupFNErr Duplicate file name and version fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBCatMoveSync æFc Files.h æT Function æTN 7005,A260 æD #pragma parameter __D0 PBCatMoveSync(__A0) pascal OSErr PBCatMoveSync(CMovePBPtr paramBlock) = {0x7005,0xA260}; æDT #pragma parameter __D0 myVariable = PBCatMoveSync()(__A0); æRI IV-157 æC •••Refer to Technical Note #226:••• Trap macro _CatMove Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 28 ioNewName pointer --> 36 ioNewDirID long word --> 48 ioDirID long word PBCatMove moves files or directories from one directory to another. The name of the file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains either the volume reference number or working directory reference number. A directory ID can be specified in ioDirID. The name and directory ID of the directory to which the file or directory is to be moved are specified by ioNewName and ioNewDirID. PBCatMove is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. PBCatMove cannot move a file or directory to another volume (that is, ioVRefNum is used in specifying both the source and the destination). It also cannot be used to rename files or directories; for that, use PBHRename. Result codes noErr No error badMovErr Attempt to move into offspring bdNamErr Bad file name or attempt to move into a file dupFNErr Duplicate file name and version fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBCatMoveAsync æFc Files.h æT Function æTN 7005,A660 æD #pragma parameter __D0 PBCatMoveAsync(__A0) pascal OSErr PBCatMoveAsync(CMovePBPtr paramBlock) = {0x7005,0xA660}; æDT #pragma parameter __D0 myVariable = PBCatMoveAsync()(__A0); æRI IV-157 æC •••Refer to Technical Note #226:••• Trap macro _CatMove Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 28 ioNewName pointer --> 36 ioNewDirID long word --> 48 ioDirID long word PBCatMove moves files or directories from one directory to another. The name of the file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains either the volume reference number or working directory reference number. A directory ID can be specified in ioDirID. The name and directory ID of the directory to which the file or directory is to be moved are specified by ioNewName and ioNewDirID. PBCatMove is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. PBCatMove cannot move a file or directory to another volume (that is, ioVRefNum is used in specifying both the source and the destination). It also cannot be used to rename files or directories; for that, use PBHRename. Result codes noErr No error badMovErr Attempt to move into offspring bdNamErr Bad file name or attempt to move into a file dupFNErr Duplicate file name and version fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDirCreate æFc Files.h æT Function æD pascal OSErr PBDirCreate(HParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBDirCreate((HParmBlkPtr) paramBlock,(Boolean) async); æRI IV-146 æC Trap macro _DirCreate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-> 48 ioDirID long word PBDirCreate is identical to PBHCreate except that it creates a new directory instead of a file. You can specify the parent of the directory to be created in ioDirID; if it’s 0, the new directory will be placed in the root directory. The directory ID of the new directory is returned in ioDirID. Warning: PBDirCreate operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full dirNFErr Directory not found or incomplete pathname extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDirCreateSync æFc Files.h æT Function æTN 7006,A260 æD #pragma parameter __D0 PBDirCreateSync(__A0) pascal OSErr PBDirCreateSync(HParmBlkPtr paramBlock) = {0x7006,0xA260}; æDT #pragma parameter __D0 myVariable = PBDirCreateSync()(__A0); æRI IV-146 æC Trap macro _DirCreate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-> 48 ioDirID long word PBDirCreate is identical to PBHCreate except that it creates a new directory instead of a file. You can specify the parent of the directory to be created in ioDirID; if it’s 0, the new directory will be placed in the root directory. The directory ID of the new directory is returned in ioDirID. Warning: PBDirCreate operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full dirNFErr Directory not found or incomplete pathname extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDirCreateAsync æFc Files.h æT Function æTN 7006,A660 æD #pragma parameter __D0 PBDirCreateAsync(__A0) pascal OSErr PBDirCreateAsync(HParmBlkPtr paramBlock) = {0x7006,0xA660}; æDT #pragma parameter __D0 myVariable = PBDirCreateAsync()(__A0); æRI IV-146 æC Trap macro _DirCreate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-> 48 ioDirID long word PBDirCreate is identical to PBHCreate except that it creates a new directory instead of a file. You can specify the parent of the directory to be created in ioDirID; if it’s 0, the new directory will be placed in the root directory. The directory ID of the new directory is returned in ioDirID. Warning: PBDirCreate operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full dirNFErr Directory not found or incomplete pathname extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBGetWDInfo æFc Files.h æT Function æD pascal OSErr PBGetWDInfo(WDPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetWDInfo((WDPBPtr) paramBlock,(Boolean) async); æRT 77, 190 æRI IV-159, N77-5 æC Trap macro _GetWDInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 26 ioWDIndex word <-> 28 ioWDProcID long word <-> 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBGetWDInfo returns information about the specified working directory. The working directory can be specified either by its working directory reference number in ioVRefNum (in which case ioWDIndex should be 0), or by its index number in ioWDIndex. In the latter case, if ioVRefNum is nonzero, it’s interpreted as a volume specification (volume reference number or drive number), and only working directories on that volume are indexed. IOWDVRefNum always returns the volume reference number. IOVRefNum returns a working directory reference number when a working directory reference number is passed in that field; otherwise, it returns a volume reference number. The volume name is returned in ioNamePtr. If IOWDProcID is nonzero, only working directories with that identifier are indexed; otherwise all working directories are indexed. Result codes noErr No error nsvErr No such volume æKY PBGetWDInfoSync æFc Files.h æT Function æTN 7007,A260 æD #pragma parameter __D0 PBGetWDInfoSync(__A0) pascal OSErr PBGetWDInfoSync(WDPBPtr paramBlock) = {0x7007,0xA260}; æDT #pragma parameter __D0 myVariable = PBGetWDInfoSync()(__A0); æRT 77, 190 æRI IV-159, N77-5 æC Trap macro _GetWDInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 26 ioWDIndex word <-> 28 ioWDProcID long word <-> 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBGetWDInfo returns information about the specified working directory. The working directory can be specified either by its working directory reference number in ioVRefNum (in which case ioWDIndex should be 0), or by its index number in ioWDIndex. In the latter case, if ioVRefNum is nonzero, it’s interpreted as a volume specification (volume reference number or drive number), and only working directories on that volume are indexed. IOWDVRefNum always returns the volume reference number. IOVRefNum returns a working directory reference number when a working directory reference number is passed in that field; otherwise, it returns a volume reference number. The volume name is returned in ioNamePtr. If IOWDProcID is nonzero, only working directories with that identifier are indexed; otherwise all working directories are indexed. Result codes noErr No error nsvErr No such volume æKY PBGetWDInfoAsync æFc Files.h æT Function æTN 7007,A660 æD #pragma parameter __D0 PBGetWDInfoAsync(__A0) pascal OSErr PBGetWDInfoAsync(WDPBPtr paramBlock) = {0x7007,0xA660}; æDT #pragma parameter __D0 myVariable = PBGetWDInfoAsync()(__A0); æRT 77, 190 æRI IV-159, N77-5 æC Trap macro _GetWDInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 26 ioWDIndex word <-> 28 ioWDProcID long word <-> 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBGetWDInfo returns information about the specified working directory. The working directory can be specified either by its working directory reference number in ioVRefNum (in which case ioWDIndex should be 0), or by its index number in ioWDIndex. In the latter case, if ioVRefNum is nonzero, it’s interpreted as a volume specification (volume reference number or drive number), and only working directories on that volume are indexed. IOWDVRefNum always returns the volume reference number. IOVRefNum returns a working directory reference number when a working directory reference number is passed in that field; otherwise, it returns a volume reference number. The volume name is returned in ioNamePtr. If IOWDProcID is nonzero, only working directories with that identifier are indexed; otherwise all working directories are indexed. Result codes noErr No error nsvErr No such volume æKY PBGetFCBInfo æFc Files.h æT Function æD pascal OSErr PBGetFCBInfo(FCBPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetFCBInfo((FCBPBPtr) paramBlock,(Boolean) async); æRT 87 æRI IV-179, N87-1 æC Trap macro _GetFCBInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word <-> 24 ioRefNum word --> 28 ioFCBIndx long word <-- 32 ioFCBFlNm long word <-- 36 ioFCBFlags word <-- 38 ioFCBStBlk word <-- 40 ioFCBEOF long word <-- 44 ioFCBPLen long word <-- 48 ioFCBCrPs long word <-- 52 ioFCBVRefNum word <-- 54 ioFCBClpSiz long word <-- 58 ioFCBParID long word PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is positive, the File Manager returns information about the file whose file number is ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive number, volume reference number, or working directory reference number). If ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed. If ioFCBIndx is 0, the File Manager returns information about the file whose access path is specified by ioRefNum. Assembly-language note: The global variable FCBSPtr points to the length word of the file-control-block buffer. Each file control block contains 94 bytes of information about an access path; Figure 28 shows its structure (using the assembly-language offsets). •••Refer to Figure 28.••• Figure 28–A File Control Block 64K ROM note: The structure of a file control block in the 64K ROM version of the File Manager is a subset of the above structure. The old file control block contained only the fields up to and including fcbFlPos. FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for PBGetFCBInfo) contains flags that describe the status of the file, as follows: Bit Meaning 0 Set if data can be written to the file 1 Set if the entry describes a resource fork 7 Set if the file has been changed since it was last flushed Warning: The size and structure of a file control block may be different in future versions of Macintosh system software. æKY PBGetFCBInfoSync æFc Files.h æT Function æTN 7008,A260 æD #pragma parameter __D0 PBGetFCBInfoSync(__A0) pascal OSErr PBGetFCBInfoSync(FCBPBPtr paramBlock) = {0x7008,0xA260}; æDT #pragma parameter __D0 myVariable = PBGetFCBInfoSync()(__A0); æRT 87 æRI IV-179, N87-1 æC Trap macro _GetFCBInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word <-> 24 ioRefNum word --> 28 ioFCBIndx long word <-- 32 ioFCBFlNm long word <-- 36 ioFCBFlags word <-- 38 ioFCBStBlk word <-- 40 ioFCBEOF long word <-- 44 ioFCBPLen long word <-- 48 ioFCBCrPs long word <-- 52 ioFCBVRefNum word <-- 54 ioFCBClpSiz long word <-- 58 ioFCBParID long word PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is positive, the File Manager returns information about the file whose file number is ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive number, volume reference number, or working directory reference number). If ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed. If ioFCBIndx is 0, the File Manager returns information about the file whose access path is specified by ioRefNum. Assembly-language note: The global variable FCBSPtr points to the length word of the file-control-block buffer. Each file control block contains 94 bytes of information about an access path; Figure 28 shows its structure (using the assembly-language offsets). •••Refer to Figure 28.••• Figure 28–A File Control Block 64K ROM note: The structure of a file control block in the 64K ROM version of the File Manager is a subset of the above structure. The old file control block contained only the fields up to and including fcbFlPos. FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for PBGetFCBInfo) contains flags that describe the status of the file, as follows: Bit Meaning 0 Set if data can be written to the file 1 Set if the entry describes a resource fork 7 Set if the file has been changed since it was last flushed Warning: The size and structure of a file control block may be different in future versions of Macintosh system software. æKY PBGetFCBInfoAsync æFc Files.h æT Function æTN 7008,A660 æD #pragma parameter __D0 PBGetFCBInfoAsync(__A0) pascal OSErr PBGetFCBInfoAsync(FCBPBPtr paramBlock) = {0x7008,0xA660}; æDT #pragma parameter __D0 myVariable = PBGetFCBInfoAsync()(__A0); æRT 87 æRI IV-179, N87-1 æC Trap macro _GetFCBInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word <-> 24 ioRefNum word --> 28 ioFCBIndx long word <-- 32 ioFCBFlNm long word <-- 36 ioFCBFlags word <-- 38 ioFCBStBlk word <-- 40 ioFCBEOF long word <-- 44 ioFCBPLen long word <-- 48 ioFCBCrPs long word <-- 52 ioFCBVRefNum word <-- 54 ioFCBClpSiz long word <-- 58 ioFCBParID long word PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is positive, the File Manager returns information about the file whose file number is ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive number, volume reference number, or working directory reference number). If ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed. If ioFCBIndx is 0, the File Manager returns information about the file whose access path is specified by ioRefNum. Assembly-language note: The global variable FCBSPtr points to the length word of the file-control-block buffer. Each file control block contains 94 bytes of information about an access path; Figure 28 shows its structure (using the assembly-language offsets). •••Refer to Figure 28.••• Figure 28–A File Control Block 64K ROM note: The structure of a file control block in the 64K ROM version of the File Manager is a subset of the above structure. The old file control block contained only the fields up to and including fcbFlPos. FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for PBGetFCBInfo) contains flags that describe the status of the file, as follows: Bit Meaning 0 Set if data can be written to the file 1 Set if the entry describes a resource fork 7 Set if the file has been changed since it was last flushed Warning: The size and structure of a file control block may be different in future versions of Macintosh system software. æKY PBGetCatInfo æFc Files.h æT Function æD pascal OSErr PBGetCatInfo(CInfoPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBGetCatInfo((CInfoPBPtr) paramBlock,(Boolean) async); æRT 68,69 æRI IV-155, V-391, N68-1, N69 æC •••Refer to Technical Note #69:••• Trap macro _GetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word <-- 24 ioFRefNum word <-- 24 ioFRefNum word --> 28 ioFDirIndex word --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 30 ioFlAttrib byte <-- 31 ioACUser byte access rights for directory only <-- 32 ioFlFndrInfo 16 bytes <-- 32 ioDrUsrWds 16 bytes <-> 48 ioDirID long word <-> 48 ioDrDirID long word <-- 52 ioFlStBlk word <-- 52 ioDrNmFls word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 72 ioDrCrDat long word <-- 76 ioFlMdDat long word <-- 76 ioDrMdDat long word <-- 80 ioFlBkDat long word <-- 80 ioDrBkDat long word <-- 84 ioFlXFndrInfo 16 bytes <-- 84 ioDrFndrInfo 16 bytes <-- 100 ioFlParID long word <-- 100 ioDrParID long word <-- 104 ioFlClpSiz long word PBGetCatInfo gets information about the files and directories in a file catalog. To determine whether the information is for a file or a directory, test bit 4 of ioFlAttrib, as described in the section “CInfoPBRec”. The information that’s returned for files is shown in the left column, and the corresponding information for directories is shown in the right column. If ioFDirIndex is positive, the File Manager returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided). If ioFDirIndex is 0, the File Manager returns information about the file or directory specified by ioNamePtr, in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided). If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns information about the directory specified by ioDirID. With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some additional information. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). For server volume directories, in addition to the normal return parameters the ioACUser field returns the user’s access rights in the following format: Bit 7 if set, user is not the owner of the directory. if clear, user is the owner of the directory. 6–3 Reserved; this is returned set to zero. 2 If set, user does not have Make Changes privileges to the directory. If clear, user has Make Changes privileges to the directory. 1 If set, user does not have See Files privileges to the directory. If clear, user has See Files privileges to the directory. 0 If set, user does not have See Folders privileges to the directory. If clear, user has See Folders privileges to the directory. For example, if ioACUser returns zero for a given server volume directory, you know that the user is the owner of the directory and has complete privileges to it. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetCatInfoSync æFc Files.h æT Function æTN 7009,A260 æD #pragma parameter __D0 PBGetCatInfoSync(__A0) pascal OSErr PBGetCatInfoSync(CInfoPBPtr paramBlock) = {0x7009,0xA260}; æDT #pragma parameter __D0 myVariable = PBGetCatInfoSync()(__A0); æRT 68,69 æRI IV-155, V-391, N68-1, N69 æC •••Refer to Technical Note #69:••• Trap macro _GetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word <-- 24 ioFRefNum word <-- 24 ioFRefNum word --> 28 ioFDirIndex word --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 30 ioFlAttrib byte <-- 31 ioACUser byte access rights for directory only <-- 32 ioFlFndrInfo 16 bytes <-- 32 ioDrUsrWds 16 bytes <-> 48 ioDirID long word <-> 48 ioDrDirID long word <-- 52 ioFlStBlk word <-- 52 ioDrNmFls word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 72 ioDrCrDat long word <-- 76 ioFlMdDat long word <-- 76 ioDrMdDat long word <-- 80 ioFlBkDat long word <-- 80 ioDrBkDat long word <-- 84 ioFlXFndrInfo 16 bytes <-- 84 ioDrFndrInfo 16 bytes <-- 100 ioFlParID long word <-- 100 ioDrParID long word <-- 104 ioFlClpSiz long word PBGetCatInfo gets information about the files and directories in a file catalog. To determine whether the information is for a file or a directory, test bit 4 of ioFlAttrib, as described in the section “CInfoPBRec”. The information that’s returned for files is shown in the left column, and the corresponding information for directories is shown in the right column. If ioFDirIndex is positive, the File Manager returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided). If ioFDirIndex is 0, the File Manager returns information about the file or directory specified by ioNamePtr, in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided). If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns information about the directory specified by ioDirID. With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some additional information. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). For server volume directories, in addition to the normal return parameters the ioACUser field returns the user’s access rights in the following format: Bit 7 if set, user is not the owner of the directory. if clear, user is the owner of the directory. 6–3 Reserved; this is returned set to zero. 2 If set, user does not have Make Changes privileges to the directory. If clear, user has Make Changes privileges to the directory. 1 If set, user does not have See Files privileges to the directory. If clear, user has See Files privileges to the directory. 0 If set, user does not have See Folders privileges to the directory. If clear, user has See Folders privileges to the directory. For example, if ioACUser returns zero for a given server volume directory, you know that the user is the owner of the directory and has complete privileges to it. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetCatInfoAsync æFc Files.h æT Function æTN 7009,A660 æD #pragma parameter __D0 PBGetCatInfoAsync(__A0) pascal OSErr PBGetCatInfoAsync(CInfoPBPtr paramBlock) = {0x7009,0xA660}; æDT #pragma parameter __D0 myVariable = PBGetCatInfoAsync()(__A0); æRT 68,69 æRI IV-155, V-391, N68-1, N69 æC •••Refer to Technical Note #69:••• Trap macro _GetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word <-- 24 ioFRefNum word <-- 24 ioFRefNum word --> 28 ioFDirIndex word --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 30 ioFlAttrib byte <-- 31 ioACUser byte access rights for directory only <-- 32 ioFlFndrInfo 16 bytes <-- 32 ioDrUsrWds 16 bytes <-> 48 ioDirID long word <-> 48 ioDrDirID long word <-- 52 ioFlStBlk word <-- 52 ioDrNmFls word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 72 ioDrCrDat long word <-- 76 ioFlMdDat long word <-- 76 ioDrMdDat long word <-- 80 ioFlBkDat long word <-- 80 ioDrBkDat long word <-- 84 ioFlXFndrInfo 16 bytes <-- 84 ioDrFndrInfo 16 bytes <-- 100 ioFlParID long word <-- 100 ioDrParID long word <-- 104 ioFlClpSiz long word PBGetCatInfo gets information about the files and directories in a file catalog. To determine whether the information is for a file or a directory, test bit 4 of ioFlAttrib, as described in the section “CInfoPBRec”. The information that’s returned for files is shown in the left column, and the corresponding information for directories is shown in the right column. If ioFDirIndex is positive, the File Manager returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided). If ioFDirIndex is 0, the File Manager returns information about the file or directory specified by ioNamePtr, in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided). If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns information about the directory specified by ioDirID. With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some additional information. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). For server volume directories, in addition to the normal return parameters the ioACUser field returns the user’s access rights in the following format: Bit 7 if set, user is not the owner of the directory. if clear, user is the owner of the directory. 6–3 Reserved; this is returned set to zero. 2 If set, user does not have Make Changes privileges to the directory. If clear, user has Make Changes privileges to the directory. 1 If set, user does not have See Files privileges to the directory. If clear, user has See Files privileges to the directory. 0 If set, user does not have See Folders privileges to the directory. If clear, user has See Folders privileges to the directory. For example, if ioACUser returns zero for a given server volume directory, you know that the user is the owner of the directory and has complete privileges to it. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBSetCatInfo æFc Files.h æT Function æD pascal OSErr PBSetCatInfo(CInfoPBPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetCatInfo((CInfoPBPtr) paramBlock,(Boolean) async); æRI IV-156 æC Trap macro _SetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word --> 30 ioFlAttrib byte --> 30 ioFlAttrib byte --> 32 ioFlFndrInfo 16 bytes --> 32 ioDrUsrWds 16 bytes --> 48 ioDirID long word --> 48 ioDrDirID long word --> 72 ioFlCrDat long word --> 72 ioDrCrDat long word --> 76 ioFlMdDat long word --> 76 ioDrMdDat long word --> 80 ioFlBkDat long word --> 80 ioDrBkDat long word --> 84 ioFlXFndrInfo 16 bytes --> 84 ioDrFndrInfo 16 bytes --> 104 ioFlClpSiz long word PBSetCatInfo sets information about the files and directories in a catalog. With files, it’s similar to PBHSetFileInfo but lets you set some additional information. The information that can be set for files is shown in the left column, and the corresponding information for directories is shown in the right column. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBSetCatInfoSync æFc Files.h æT Function æTN 700A,A260 æD #pragma parameter __D0 PBSetCatInfoSync(__A0) pascal OSErr PBSetCatInfoSync(CInfoPBPtr paramBlock) = {0x700A,0xA260}; æDT #pragma parameter __D0 myVariable = PBSetCatInfoSync()(__A0); æRI IV-156 æC Trap macro _SetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word --> 30 ioFlAttrib byte --> 30 ioFlAttrib byte --> 32 ioFlFndrInfo 16 bytes --> 32 ioDrUsrWds 16 bytes --> 48 ioDirID long word --> 48 ioDrDirID long word --> 72 ioFlCrDat long word --> 72 ioDrCrDat long word --> 76 ioFlMdDat long word --> 76 ioDrMdDat long word --> 80 ioFlBkDat long word --> 80 ioDrBkDat long word --> 84 ioFlXFndrInfo 16 bytes --> 84 ioDrFndrInfo 16 bytes --> 104 ioFlClpSiz long word PBSetCatInfo sets information about the files and directories in a catalog. With files, it’s similar to PBHSetFileInfo but lets you set some additional information. The information that can be set for files is shown in the left column, and the corresponding information for directories is shown in the right column. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBSetCatInfoAsync æFc Files.h æT Function æTN 700A,A660 æD #pragma parameter __D0 PBSetCatInfoAsync(__A0) pascal OSErr PBSetCatInfoAsync(CInfoPBPtr paramBlock) = {0x700A,0xA660}; æDT #pragma parameter __D0 myVariable = PBSetCatInfoAsync()(__A0); æRI IV-156 æC Trap macro _SetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word --> 30 ioFlAttrib byte --> 30 ioFlAttrib byte --> 32 ioFlFndrInfo 16 bytes --> 32 ioDrUsrWds 16 bytes --> 48 ioDirID long word --> 48 ioDrDirID long word --> 72 ioFlCrDat long word --> 72 ioDrCrDat long word --> 76 ioFlMdDat long word --> 76 ioDrMdDat long word --> 80 ioFlBkDat long word --> 80 ioDrBkDat long word --> 84 ioFlXFndrInfo 16 bytes --> 84 ioDrFndrInfo 16 bytes --> 104 ioFlClpSiz long word PBSetCatInfo sets information about the files and directories in a catalog. With files, it’s similar to PBHSetFileInfo but lets you set some additional information. The information that can be set for files is shown in the left column, and the corresponding information for directories is shown in the right column. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBAllocContig æFc Files.h æT Function æD pascal OSErr PBAllocContig(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBAllocContig((ParmBlkPtr) paramBlock,(Boolean) async); æRI IV-143 æC Trap macro _AllocContig Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocContig is identical to PBAllocate except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContig will do nothing and will return dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled as a contiguous piece, call PBAllocate instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBAllocContigSync æFc Files.h æT Function æTN A210 æD #pragma parameter __D0 PBAllocContigSync(__A0) pascal OSErr PBAllocContigSync(ParmBlkPtr paramBlock) = 0xA210; æDT #pragma parameter __D0 myVariable = PBAllocContigSync()(__A0); æRI IV-143 æC Trap macro _AllocContig Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocContig is identical to PBAllocate except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContig will do nothing and will return dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled as a contiguous piece, call PBAllocate instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBAllocContigAsync æFc Files.h æT Function æTN A610 æD #pragma parameter __D0 PBAllocContigAsync(__A0) pascal OSErr PBAllocContigAsync(ParmBlkPtr paramBlock) = 0xA610; æDT #pragma parameter __D0 myVariable = PBAllocContigAsync()(__A0); æRI IV-143 æC Trap macro _AllocContig Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocContig is identical to PBAllocate except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContig will do nothing and will return dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled as a contiguous piece, call PBAllocate instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBLockRange æFc Files.h æT Function æD pascal OSErr PBLockRange(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBLockRange((ParmBlkPtr) paramBlock,(Boolean) async); æRT 186 æRI IV-138 æC •••Refer to Technical Note #186:••• Trap macro _LockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word On a file opened with a shared read/write permission, PBLockRange is used in conjunction with PBRead and PBWrite to lock a certain portion of the file. PBLockRange uses the same parameters as both PBRead and PBWrite; by calling it immediately before PBRead, you can use the information present in the parameter block for the PBRead call. When you’re finished with the data (typically after a call to PBWrite), be sure to call PBUnlockRange to free up that portion of the file for subsequent PBRead calls. Warning: PBLockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBLockRangeSync æFc Files.h æT Function æTN 7010,A260 æD #pragma parameter __D0 PBLockRangeSync(__A0) pascal OSErr PBLockRangeSync(ParmBlkPtr paramBlock) = {0x7010,0xA260}; æDT #pragma parameter __D0 myVariable = PBLockRangeSync()(__A0); æRT 186 æRI IV-138 æC •••Refer to Technical Note #186:••• Trap macro _LockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word On a file opened with a shared read/write permission, PBLockRange is used in conjunction with PBRead and PBWrite to lock a certain portion of the file. PBLockRange uses the same parameters as both PBRead and PBWrite; by calling it immediately before PBRead, you can use the information present in the parameter block for the PBRead call. When you’re finished with the data (typically after a call to PBWrite), be sure to call PBUnlockRange to free up that portion of the file for subsequent PBRead calls. Warning: PBLockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBLockRangeAsync æFc Files.h æT Function æTN 7010,A660 æD #pragma parameter __D0 PBLockRangeAsync(__A0) pascal OSErr PBLockRangeAsync(ParmBlkPtr paramBlock) = {0x7010,0xA660}; æDT #pragma parameter __D0 myVariable = PBLockRangeAsync()(__A0); æRT 186 æRI IV-138 æC •••Refer to Technical Note #186:••• Trap macro _LockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word On a file opened with a shared read/write permission, PBLockRange is used in conjunction with PBRead and PBWrite to lock a certain portion of the file. PBLockRange uses the same parameters as both PBRead and PBWrite; by calling it immediately before PBRead, you can use the information present in the parameter block for the PBRead call. When you’re finished with the data (typically after a call to PBWrite), be sure to call PBUnlockRange to free up that portion of the file for subsequent PBRead calls. Warning: PBLockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBUnlockRange æFc Files.h æT Function æD pascal OSErr PBUnlockRange(ParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBUnlockRange((ParmBlkPtr) paramBlock,(Boolean) async); æRT 186 æRI IV-139 æC Trap macro _UnlockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain portion of a file that you locked with PBLockRange. Warning: PBUnlockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBUnlockRangeSync æFc Files.h æT Function æTN 7011,A260 æD #pragma parameter __D0 PBUnlockRangeSync(__A0) pascal OSErr PBUnlockRangeSync(ParmBlkPtr paramBlock) = {0x7011,0xA260}; æDT #pragma parameter __D0 myVariable = PBUnlockRangeSync()(__A0); æRT 186 æRI IV-139 æC Trap macro _UnlockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain portion of a file that you locked with PBLockRange. Warning: PBUnlockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBUnlockRangeAsync æFc Files.h æT Function æTN 7011,A660 æD #pragma parameter __D0 PBUnlockRangeAsync(__A0) pascal OSErr PBUnlockRangeAsync(ParmBlkPtr paramBlock) = {0x7011,0xA660}; æDT #pragma parameter __D0 myVariable = PBUnlockRangeAsync()(__A0); æRT 186 æRI IV-139 æC Trap macro _UnlockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain portion of a file that you locked with PBLockRange. Warning: PBUnlockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBSetVInfo æFc Files.h æT Function æD pascal OSErr PBSetVInfo(HParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBSetVInfo((HParmBlkPtr) paramBlock,(Boolean) async); æRT 204 æRI IV-131 æC •••Refer to Technical Note #204:••• Trap macro _SetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 30 ioVCrDate long word --> 34 ioVLsMod long word --> 38 ioVAtrb word --> 52 ioVClpSiz long word --> 72 ioVBkUp long word --> 76 ioVSeqNum word --> 90 ioVFndrInfo 32 bytes PBSetVInfo lets you modify information about volumes. A pointer to a new name for the volume can be specified in ioNamePtr. The date and time of the volume’s creation and modification can be set with ioVCrDate and ioVLsMod respectively. Only bit 15 of ioVAtrb can be changed; setting it locks the volume. Note: The volume cannot be specified by name; you must use either the volume reference number or the drive number. Warning: PBSetVInfo operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBSetVInfoSync æFc Files.h æT Function æTN 700B,A260 æD #pragma parameter __D0 PBSetVInfoSync(__A0) pascal OSErr PBSetVInfoSync(HParmBlkPtr paramBlock) = {0x700B,0xA260}; æDT #pragma parameter __D0 myVariable = PBSetVInfoSync()(__A0); æRT 204 æRI IV-131 æC •••Refer to Technical Note #204:••• Trap macro _SetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 30 ioVCrDate long word --> 34 ioVLsMod long word --> 38 ioVAtrb word --> 52 ioVClpSiz long word --> 72 ioVBkUp long word --> 76 ioVSeqNum word --> 90 ioVFndrInfo 32 bytes PBSetVInfo lets you modify information about volumes. A pointer to a new name for the volume can be specified in ioNamePtr. The date and time of the volume’s creation and modification can be set with ioVCrDate and ioVLsMod respectively. Only bit 15 of ioVAtrb can be changed; setting it locks the volume. Note: The volume cannot be specified by name; you must use either the volume reference number or the drive number. Warning: PBSetVInfo operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBSetVInfoAsync æFc Files.h æT Function æTN 700B,A660 æD #pragma parameter __D0 PBSetVInfoAsync(__A0) pascal OSErr PBSetVInfoAsync(HParmBlkPtr paramBlock) = {0x700B,0xA660}; æDT #pragma parameter __D0 myVariable = PBSetVInfoAsync()(__A0); æRT 204 æRI IV-131 æC •••Refer to Technical Note #204:••• Trap macro _SetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 30 ioVCrDate long word --> 34 ioVLsMod long word --> 38 ioVAtrb word --> 52 ioVClpSiz long word --> 72 ioVBkUp long word --> 76 ioVSeqNum word --> 90 ioVFndrInfo 32 bytes PBSetVInfo lets you modify information about volumes. A pointer to a new name for the volume can be specified in ioNamePtr. The date and time of the volume’s creation and modification can be set with ioVCrDate and ioVLsMod respectively. Only bit 15 of ioVAtrb can be changed; setting it locks the volume. Note: The volume cannot be specified by name; you must use either the volume reference number or the drive number. Warning: PBSetVInfo operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBHGetVInfo æFc Files.h æT Function æD pascal OSErr PBHGetVInfo(HParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBHGetVInfo((HParmBlkPtr) paramBlock,(Boolean) async); æRT 24, 66, 67, 77, 106, 157 æRI IV-130, N66-1, N67-1, N77-5 æC Trap macro _HGetVInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsMod long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVBitMap word <-- 44 ioVAllocPtr word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word <-- 64 ioVSigWord word <-- 66 ioVDrvInfo word <-- 68 ioVDRefNum word <-- 70 ioVFSID word <-- 72 ioVBkUp long word <-- 76 ioVSeqNum word <-- 78 ioVWrCnt long word <-- 82 ioVFilCnt long word <-- 86 ioVDirCnt long word <-- 90 ioVFndrInfo 32 bytes PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter block. In addition, PBHGetVInfo always returns the volume reference number in ioVRefNum (regardless of what was passed in). Also, ioVNmAlBlks and ioVFrBlks are not clipped as they are by PBGetVInfo. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBHGetVInfoSync æFc Files.h æT Function æTN A207 æD #pragma parameter __D0 PBHGetVInfoSync(__A0) pascal OSErr PBHGetVInfoSync(HParmBlkPtr paramBlock) = 0xA207; æDT #pragma parameter __D0 myVariable = PBHGetVInfoSync()(__A0); æRT 24, 66, 67, 77, 106, 157 æRI IV-130, N66-1, N67-1, N77-5 æC Trap macro _HGetVInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsMod long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVBitMap word <-- 44 ioVAllocPtr word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word <-- 64 ioVSigWord word <-- 66 ioVDrvInfo word <-- 68 ioVDRefNum word <-- 70 ioVFSID word <-- 72 ioVBkUp long word <-- 76 ioVSeqNum word <-- 78 ioVWrCnt long word <-- 82 ioVFilCnt long word <-- 86 ioVDirCnt long word <-- 90 ioVFndrInfo 32 bytes PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter block. In addition, PBHGetVInfo always returns the volume reference number in ioVRefNum (regardless of what was passed in). Also, ioVNmAlBlks and ioVFrBlks are not clipped as they are by PBGetVInfo. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBHGetVInfoAsync æFc Files.h æT Function æTN A607 æD #pragma parameter __D0 PBHGetVInfoAsync(__A0) pascal OSErr PBHGetVInfoAsync(HParmBlkPtr paramBlock) = 0xA607; æDT #pragma parameter __D0 myVariable = PBHGetVInfoAsync()(__A0); æRT 24, 66, 67, 77, 106, 157 æRI IV-130, N66-1, N67-1, N77-5 æC Trap macro _HGetVInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsMod long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVBitMap word <-- 44 ioVAllocPtr word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word <-- 64 ioVSigWord word <-- 66 ioVDrvInfo word <-- 68 ioVDRefNum word <-- 70 ioVFSID word <-- 72 ioVBkUp long word <-- 76 ioVSeqNum word <-- 78 ioVWrCnt long word <-- 82 ioVFilCnt long word <-- 86 ioVDirCnt long word <-- 90 ioVFndrInfo 32 bytes PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter block. In addition, PBHGetVInfo always returns the volume reference number in ioVRefNum (regardless of what was passed in). Also, ioVNmAlBlks and ioVFrBlks are not clipped as they are by PBGetVInfo. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBHOpen æFc Files.h æT Function æD pascal OSErr PBHOpen(HParmBlkPtr paramBlock,Boolean async); æDT OSErr myVariable = PBHOpen((HParmBlkPtr) paramBlock,(Boolean) async); æRT 204 æRI IV-136 æC Trap macro _HOpen Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 27 ioPermssn byte --> 28 ioMisc pointer --> 48 ioDirID long word PBHOpen is identical to PBOpen except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBHOpenSync æFc Files.h æT Function æTN A200 æD #pragma parameter __D0 PBHOpenSync(__A0) pascal OSErr PBHOpenSync(HParmBlkPtr paramBlock) = 0xA200; æDT #pragma parameter __D0 myVariable = PBHOpenSync()(__A0); æRT 204 æRI IV-136 æC Trap macro _HOpen Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 27 ioPermssn byte --> 28 ioMisc pointer --> 48 ioDirID long word PBHOpen is identical to PBOpen except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBHOpenAsync æFc Files.h æT Function æTN A600 æ